Clean up docstrings

[OndrejMarsalek]

I moved and merged documentation text from README files to package __init__.py files and from module docstrings to the classes and functions themselves. This makes automatically extracted documentation better and removes lists of stuff that need to be maintained by hand. I already found several places where it was out of sync and it would only be worse.

If we also want to remove the license notices from the docstrings, as I think we should, do not merge it.

Fixes #46.

[tomspur]

The license notices can be removed from the docstrings, but they should be moved to the top of the file and commented out with ´#´. This way, they are not part of the sphinx documentation, but still there and license can be checked recursively with licensecheck -v.

[OndrejMarsalek]

Yep, that's what I meant. You can see a suggestion of what I think it should look like in ipi/utils/depend.py. I just did not want to do all the editing before it gets the blessing of @ceriottm. I think docstring first, license info second is better, but the other way around could also work.

[ceriottm]

I agree with this. A few remarks:

• please figure out which order (license first/license last) is standard,
• please keep the dual GPL/BSD license
• I don't care so much what we do with year and the copyright notice. Just let's leave it as simple as possible, and let's leave in each file/subroutine the possibility to explicitly mention the contributions. I feel it is always good to give contributors as much credit as possible.

[OndrejMarsalek]

• This took a bit of digging, but it is now clear to me that this is far from standard. Some projects do not include the per-file boilerplate at all and only have a LICENSE file. In fact, it appears to be only a recommendation, but not a requirement:

  http://stackoverflow.com/questions/6859820/gpl-boilerplate/6878709#6878709

  If we want to keep it anyway (I have no strong preference either way), it should be fine before or after the docstring.

• The years should be all release years, but again, the actual practice is somewhat unclear. Considering that it is being used from the repository anyway, the full range should be fine.

• I see that we have files for GPL and MIT included under licenses. Is that what you mean by the dual license? It looks like these go in the root for most projects, but "somewhere" is sufficient for it to be valid.

• I am not sure I understand the need for GPL if you want to license under MIT anyway. What does GPL give us in addition? This is not of concern until release, though.

• I would do what you can currently see as an example in the file ipi//utils/depend.py in this branch. Can you confirm or modify this for other files?

• If you want to include contributors for each file, I would have another comment block under the boilerplate as "# Contributors:" and a list. I agree that giving credit is always a good thing, but I am quite skeptical how practical it is at this resolution. Some contributions to a project are hard to localize, with some it is difficult to determine the cut for what is a "contribution" to a given file. Is a one line change enough? What if it is a critical bug fix? Who decides and keeps track by hand? The more open the development becomes, the more messy and hard to track this is. Wouldn't it be better to just do this at the level of the whole project with two or three levels? Perhaps something like "lead developer", "developers" and "with contributions from"? After all, the repository has all the details of who wrote or modified what, if that's what someone is interested in. Finally, is it the case even now that contributors are explicitly listed where they wrote code, or would someone have to go over it and make the calls?

[OndrejMarsalek]

@ceriottm, can I please get your input on this? I would like to merge it as soon as possible so that I don't have to maintain it in sync with master. Basically the main thing is the new license block, the rest can be discussed separately.

[ceriottm]

On 15 June 2015 at 02:22, Ondrej Marsalek [email protected] wrote:

This took a bit of digging, but it is now clear to me that this is far
from standard. Some projects do not include the per-file boilerplate at all
and only have a LICENSE file. In fact, it appears to be only a
recommendation, but not a requirement:

http://stackoverflow.com/questions/6859820/gpl-boilerplate/6878709#6878709

If we want to keep it anyway (I have no strong preference either way),
it should be fine before or after the docstring.

I think that IF it is not a requirement we should reduce the boilerplate
to a minimum. Perhaps just

Copyright (C) 2014-2015, The i-PI Developers

See LICENSE for detailed license information

The years should be all release years, but again, the actual practice
is somewhat unclear. Considering that it is being used from source anyway,
the full range should be fine.

I see that we have files for GPL and MIT included under licenses. Is
that what you mean by the dual license? It looks like these mostly go in
the root, but "somewhere" is sufficient for it to be valid.

Fine for me to move them to LICENSE in the root

I am not sure I understand the need for GPL if you want to license
under MIT anyway. What does GPL give us in addition? This is not of concern
until release, though.

I had a discussion with someone back than that convinced me it was the
best idea.Can't remember the rationale though, as you say MIT is a
do-as-you-wish thing so GPL is sort of useless if one can choose.

I would do what you can currently see as an example in the file
ipi//utils/depend.py in this branch. Can you confirm or modify this
for other files?

I have to check.

If you want to include contributors for each file, I would have
another comment block under the boilerplate as "# Contributors:" and a
list. I agree that giving credit is always a good thing, but I am quite
skeptical how practical it is at this resolution. Some contributions to a
project are hard to localize, with some it is difficult to determine the
cut for what is a "contribution" to a given file. If is a one line change
enough? What if it is a critical bug fix? Who decides and keeps track by
hand? The more open the development becomes, the more messy and hard to
track this is. Wouldn't it be better to just do this at the level of the
whole project with two or three levels? Perhaps something like "lead
developer", "developers" and "with contributions from"? After all, the
repository has all the details of who wrote or modified what, if that's
what someone is interested in. Finally, is it the case even now that
contributors are explicitly listed where they wrote code, or wou ld someone
have to go over it and make the calls?

Agree, this is messy. Let's stay with project-wide credits. Perhaps a
CREDITS file?

—
Reply to this email directly or view it on GitHub
#50 (comment).

[OndrejMarsalek]

Minimal copyright notice sounds good, will prepare it like that. I would also put an explicit statement (one sentence) on licensing in the readme file.

The AUTHORS file is customary for a list of developers, so I'd say go with that.

I did not mean to say that I don't like the license directory, I just wanted to clarify. I think that either the way it is now or two files in the root, something like LICENSE.GPL and LICENSE.MIT are fine.

Regarding dual licensing. The beginning of the accepted answer below suggests that having GPL as well allows derivative work to also use GPL, which is not possible with MIT.

http://programmers.stackexchange.com/questions/139663/confusion-about-dual-license-mit-gpl-javascript-for-use-on-my-website

Anyway, that's for later, I would say. The copyright notice does not depend on it.

[OndrejMarsalek]

So in this branch, I will remove the boilerplate from docstrings and add the shorter copyright notice as a comment block under the docstring. Then we are ready to merge. Sounds good?

[OndrejMarsalek]

This is what I would use (example in depend.py):

# This file is part of i-PI.
# i-PI Copyright (C) 2014-2015 i-PI developers
# See the "licenses" directory for full license information.

[tomspur]

I pointed out that GPL for the socket implementation is not the best idea as it cannot be used in non-GPLed programs with simple copy&paste and adopting to their code base as it would make the whole code base GPL. One alternative would be LGPL for that part, but I think MIT is even more permissive and should be used at least for that part of the code.

I didn't know, that you want to release the whole code under MIT. Maybe GPL would be better, so that anyone who makes changes to the code must also publish it? (Exactly what I want to avoid with MIT for the socket part...)

[ceriottm]

As @ondrej pointed out, the rationale for dual licensing was to allow
maximum freedom at all levels, but also to encourage (and perhaps make
possible) GPL derivatives to be produced.

On 21 June 2015 at 22:45, Thomas Spura [email protected] wrote:

I pointed out that GPL for the socket implementation is not the best idea
as it cannot be used in non-GPLed programs with simple copy&paste and
adopting to their code base as it would make the whole code base GPL. One
alternative would be LGPL for that part, but I think MIT is even more
permissive and should be used at least for that part of the code.

I didn't know, that you want to release the whole code under MIT. Maybe
GPL would be better, so that anyone who makes changes to the code must also
publish it? (Exactly what I want to avoid with MIT for the socket part...)

—
Reply to this email directly or view it on GitHub
#50 (comment).

[OndrejMarsalek]

Let's continue under #67 and close this pull request once I put in the new copyright block.

[OndrejMarsalek]

This is ready for a merge as far as I am concerned.

[ceriottm]

green lights!

On 27 June 2015 at 01:52, Ondrej Marsalek [email protected] wrote:

This is ready for a merge as far as I am concerned.

—
Reply to this email directly or view it on GitHub
#50 (comment).