On 9/16/20 12:05 PM, Christophe de Dinechin wrote:
On 16 Sep 2020, at 17:47, John Snow <js...@redhat.com> wrote:
For some of the Python cleanup work I am doing, I am moving preamble comments
into docstrings. These docstrings are visible in interactive editors and may be
visible when using Sphinx to generate documentation manuals for Python code.
My instinct is to remove the licensing and authorship information from the
preamble and leave the docstring only with information functionally relevant to
the module, while leaving licensing and authorship information in a comment
(above? below?).
The end effect would be that using e.g. `help(qapi.parser)` in the interactive
Python shell would not show licensing or copyright for the module, but it would
still be visible in the source file, as always.
Is this in bad taste? Do we have strong feelings about authorship and licensing
being visible in help output and generated documentation?
What about putting that in a separate pseudo-entity, so that help(copyright)
would show it?
help is a Python builtin that shows metadata about an object. If an
object has a docstring, it is capable of displaying that as part of the
help output. I'm not sure what type you are suggesting `copyright` to be.
So, you could do something like:
__copyright__ == """
Copyright (C) 2020 John Snow, for Red Hat Inc.
"""
And you could then theoretically do:
>>> import qapi
>>> qapi.__copyright__
which will show you that information. However, I don't think there's any
standard for module-level metadata like this, so the odds of this
information being seen or used is low.
Python has some standards for package-level metadata, but I don't think
there are any standards for module-level metadata *except* the __doc__
attribute -- which is where the module-level docstring goes when we
write one.
The real question I have is if anyone thinks it would be "rude" to
separate out any of the comment preambles (currently not visible at
runtime or docs in any way, shape or form!) into two pieces:
1. Functional stuff relating to the usage of the module, visible in
help(module_name), visible in generated docs, visible in IDE popups, etc.
2. Authorship/copyright and licensing info, not visible in the above places.
--js
