[Doc-SIG] Docstrings Format

[Moshe Zadka]

On Tue, 7 Nov 2000, Mark Hammond wrote:

> I agree with the goals in general, but agree with Ken's new goal.  As a
> nit-pick:
>     3. It must not contain information which can be deduced from parsing
>        the module.
> 
> maybe needs to be reworded slightly, as docstrings generally _do_ include
> redundant information such as the function and parameter names, even though
> these are obviously able to be deduced.

Well, yes, a rewording is in order. What I meant that it must not be the
case that you *have* to include information which can be deduced from
parsing the module.

> However, your PEP as it stands doesnt actually _say_ anything!  As the PEP
> itself says, you have rehashed what as already been discussed ad-nauseam
> right here.

That's right -- but I seem to remember we had some discrepencies about
the *goals* of the docstring format. As long as we're sure we agree
on the goals, we can move on with the format.

> I would vote that we explicitly state a goal is to use StructuredTextNG if
> possible, and that the focus of the PEP then become two-fold:
> * Identifying and fixing limitations in StructuredTextNG, as relevant to
> Python docstrings.
> * A specific, concrete markup proposal for Python docstrings (ie, narrow the
> flexibility of StructuredTextNG to a reasonable subset for Python that
> docstring tools can rely on.)

Well, in the time-honoured Guido tradition of not listening to votes but
to arguments, I have to say yours makes a lot of sense. That's two people
who already suggested ST-NG, so I'll have to take a look at it.

--
Moshe Zadka <moshez@math.huji.ac.il> -- 95855124
http://advogato.org/person/moshez