[Doc-SIG] Re: Attribute docstrings

[David Goodger]

Beni Cherniavsky wrote:
 > What?!?  You are initializing a value in code *only* because that's
 > a precondition to the docstring being recognized?  Not having seen
 > the code, I can't say whether initializing it there is healthy on
 > other merits -- but it certainly sounds bad that the documentation
 > format forces you to write code in a certain way.

When you put it that way, it does sound bad.

I like to think of it in terms of optional functionality, so you don't
*have* to use it if you don't want to.  Docstring writers are welcome
to describe attributes in class docstrings with definition lists, etc.

 > Let me join the "Urf" sentiment.  I've resented this solution/syntax
 > since I saw it for the following reasons:
 >
 > * It provides no way to introspect these docstrings.  That's a
 >   design decision:

Yes, it was.  The same syntax was proposed in PEP 224, with support
for introspection, but was rejected.  That's why PEP 258 proposes it
as a convention in application space, without requiring Python
interpreter support.

 >   I can understand the desire for "secondary" docstrings to limit
 >   code bloat but who said that *all* attribute docstrings *must* be
 >   secondary?  What if do want them at runtime (and I do)?  Why
 >   shouldn't I have the option?

If you'd like to lobby for that option, please go ahead.  Start with
PEP 224, and come up with a better syntax or solution.  In PEP 258 I
intentionally avoided the issue.

 > For all these reasons, I propose the following extremely unmagical
 > solution: all bare-string statements are simply concatenated
 > together to form this scope's docstring.

That's a good idea.  It could be an alternative to attribute
docstrings.  In any case, I'll document it in the PEP.

 > Well, not simply - at least a newline (or two?) should be inserted
 > because most docstrings don't end with one.

Two.  Extra newlines don't hurt.

 > In other words, we simply allow the docstring to be split into parts
 > with code between them, which brings docstrings one step closer to
 > literate programming.
 >
 > The examples from `PEP 258`__ then become::
 >
 >     """g
 >         This is g's docstring."""
 >     g = 'module attribute (module-global variable)'

I see two problems with that:

1. You have redundant information: the attribute name.  The "magic"
    equivalent doesn't need that repetition.

2. As Edward pointed out, getting the relative indentations right is
    very tricky.  The first line of the docstring has no indentation at
    all.

But it is a simpler proposal, much easier to explain and understand.

 >     def f(x):
 >         """Function f's docstring."""
 >         return x**2
 >
 >         """a
 >             Function attribute f.a's docstring."""
 >
 >     f.a = 1

This is stretching things a bit.  I understand why the docstring is at
a different indentation level (inside the function), but there's too
much of a disconnect for my liking.

-- David Goodger