On Sun, Jul 26, 2009 at 2:49 PM, Erwin Mueller<dev...@deventm.org> wrote: > Hello, I'm new to Python (using it for two months) and I wonder how can I > comment the const. values with the doc-strings. I.e. if I have code:
>>FRACTION_MIN = 1 >>FRACTION_MAX = 10
>>class Fraction(collections.MutableSequence): >> '''Model a fraction with denominators.
>> It contains one ore more denomintors in a list for quick access. >> The class is thread save, it uses a lock for all operations. >> '''
>> def __init__(self): >> # ...
> The class and the methods can have doc-strings, but what about the const. > values, FRACTION_MIN and FRACTION_MAX?
Only modules, classes, and functions/methods can have docstrings associated with them. For anything else, you have to use comments; or you can mention them in the docstrings of related things.
> Only modules, classes, and functions/methods can have docstrings > associated with them. > For anything else, you have to use comments; or you can mention them > in the docstrings of related things.
What about adding docstrings to other Python things, especially to variables?
> On Sun, Jul 26, 2009 at 2:49 PM, Erwin Mueller<dev...@deventm.org> wrote: >> Hello, I'm new to Python (using it for two months) and I wonder how can I >> comment the const. values with the doc-strings. I.e. if I have code:
>>> FRACTION_MIN = 1 >>> FRACTION_MAX = 10
>>> class Fraction(collections.MutableSequence): >>> '''Model a fraction with denominators.
>>> It contains one ore more denomintors in a list for quick access. >>> The class is thread save, it uses a lock for all operations. >>> '''
>>> def __init__(self): >>> # ... >> The class and the methods can have doc-strings, but what about the const. >> values, FRACTION_MIN and FRACTION_MAX?
> Only modules, classes, and functions/methods can have docstrings > associated with them. > For anything else, you have to use comments; or you can mention them > in the docstrings of related things.
While this is technically true, writing docstrings to constants (module or classlevel) works when one uses tools such as epydoc to generate documentation.
On Sun, 26 Jul 2009 15:42:22 -0700, Bearophile wrote: > Chris Rebert: >> Only modules, classes, and functions/methods can have docstrings >> associated with them. >> For anything else, you have to use comments; or you can mention them in >> the docstrings of related things.
> What about adding docstrings to other Python things, especially to > variables?
Python doesn't have variables, it has objects bound to names. Because __doc__ is looked up on the class, not the instance, there's not much point in adding a docstring to the instance (even for instances which allow attributes to be added). And because names are internally stored as strings, you can't add a docstring to the name. So what you ask for is impossible.
But of course that could be changed, if there was consensus that what you ask for would be useful. But consider the consequences:
# A thought-experiment
>>> margin = 3 # allow a little bit of whitespace >>> margin.__doc__ = "Extra space in pixels." >>> help(x)
=> displays "Extra space in pixels."
So far so good. But now consider two equally unacceptable situations:
(1) If the docstring sticks to the object, then you get the docstring inappropriately showing up in places where it should:
Now, in a large program, one shouldn't recycle names like that, but in a large program, you're unlikely to programmatically look up docstrings. Docstrings, and the help() function, are particularly useful in an interactive session, which is precisely the time that you're likely to recycle names.
In other words, it's currently impossible to bind docstrings to "variables" in Python, but even more fundamentally, the request is semantically incompatible with the Python name/object binding model.
On Mon, 27 Jul 2009 00:47:08 +0200, Diez B. Roggisch wrote: >> Only modules, classes, and functions/methods can have docstrings >> associated with them. >> For anything else, you have to use comments; or you can mention them in >> the docstrings of related things.
> While this is technically true, writing docstrings to constants (module > or classlevel) works when one uses tools such as epydoc to generate > documentation.
I've never used epydoc, so I'm not sure what you mean. Presumably it uses source code analysis to detect:
CONSTANT = 42 """This is a constant."""
even though the string is ignored by the compiler.
> On Mon, 27 Jul 2009 00:47:08 +0200, Diez B. Roggisch wrote:
>>> Only modules, classes, and functions/methods can have docstrings >>> associated with them. >>> For anything else, you have to use comments; or you can mention them in >>> the docstrings of related things. >> While this is technically true, writing docstrings to constants (module >> or classlevel) works when one uses tools such as epydoc to generate >> documentation.
> I've never used epydoc, so I'm not sure what you mean. Presumably it uses > source code analysis to detect:
> CONSTANT = 42 > """This is a constant."""
> even though the string is ignored by the compiler.
> Is that correct?
epydoc 3 can actually parse the file to grab comments with a "#:" marker:
#: This is a constant. CONSTANT = 42
-- Robert Kern
"I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth." -- Umberto Eco
Steven D'Aprano wrote: > On Mon, 27 Jul 2009 00:47:08 +0200, Diez B. Roggisch wrote:
>>> Only modules, classes, and functions/methods can have docstrings >>> associated with them. >>> For anything else, you have to use comments; or you can mention them in >>> the docstrings of related things.
>> While this is technically true, writing docstrings to constants (module >> or classlevel) works when one uses tools such as epydoc to generate >> documentation.
> I've never used epydoc, so I'm not sure what you mean. Presumably it uses > source code analysis to detect:
> CONSTANT = 42 > """This is a constant."""
> even though the string is ignored by the compiler.
> Is that correct?
Yes, and because it is perfectly ignored by the compiler there's no harm using this feature. I would add that even if you're not using epydoc, having a way top discriminate comments from documentation is recommended, their purpose are definitely not the same.
