module attributes and docstrings

[Mario Figueiredo]

Sorry for the late reply. We experienced a 3 day blackout following
one of the most amazing thunderstorms I've witnessed in my life.

On Tue, 24 Mar 2015 22:49:49 +1100, Steven D'Aprano
<steve+comp.lang.python at pearwood.info> wrote:

>On Tue, 24 Mar 2015 07:55 pm, Mario Figueiredo wrote:
>
>> Reading PEP 257 and 258 I got the impression that I could document
>> module attributes and these would be available in the __doc__
>> attribute of the object.
>
>PEP 258 is rejected, so you can't take that as definitive.

Ah! That explains it then. Thank you.

(Also learned to start paying more attention to the status field).

>
>PEP 257 has this definition very early in the document:
>
>    A docstring is a string literal that occurs as the first 
>    statement in a module, function, class, or method definition.
>
>
>Nothing there about documenting arbitrary attributes.

That did get me a little confused. But since PEP 258 required PEP 257,
I just assumed the former would redefine the latter and didn't make
much of the apparent contradiction.

>
>Even if there was support from the compiler to extract the docstring, where
>would it be stored? Consider:
>
>spam = None
>"""Spammy goodness."""
>eggs = None
>"""Scrambled, not fried."""
>
>There's only one None object, and even if it could take a docstring (and it
>can't), which docstring would it get? Presumably the second, which would
>make help(spam) confusing, but when we say eggs = 23 the docstring would
>disappear too.

This is a byproduct of me still thinking in terms of C variables. When
I first read that paragraph of yours, it didn't make sense to me --
"What is he talking about? I'm documenting the spam and eggs
identifiers, not the None object".

But when I was trying to reply to you by mounting a case around
writing directly to the __doc__ attribute of the spam and eggs
identifiers, the python shell was quick to make me realized my
foolishness, and I remembered about Python variables not being the
same as C variables.