[Doc-SIG] docstring grammar

[Robin Friedrich]

From: Fred L. Drake, Jr. <fdrake@acm.org>
> Mark Hammond writes:
>  > * IMO, importing the module to extract this information is fine.  For
>  > the 1% of cases where it is not and the author of the module needs to
>
>   No, it's not.  Never trust someone else's code until you've read the
> documentation, and don't trust the documentation if they wrote it.
> Well, maybe *that's* going a little too far... but import is not
> acceptable.  Using the parse tree also allows the order to be
> well-defined, while introspection doesn't allow that at all.

We could argue this forever. Gendoc solved this by collecting info either
way, based on a runtime switch. As an author running this tool obviously I
trust the module/package to be imported and generate the docs that way. And
of course C module doc strings will need this feature.
Again, this is an application issue not a doc string grammar issue.
>
>  > chance of it one day existing :-)  Indeed, do it the simple way, and
>  > the first person who needs the parse-only option can help code it :-)
>
>   I maintain that the parse tree is the simple route to getting a
> reliable tool, and I am working on coding one.  Neat, huh?

I hope everyone slinging code looks at pythondoc first.

-Robin