[Doc-SIG] Docstrings Format
Moshe Zadka <firstname.lastname@example.org>
Tue, 7 Nov 2000 05:33:06 +0200 (IST)
On Tue, 7 Nov 2000, Mark Hammond wrote:
> I agree with the goals in general, but agree with Ken's new goal. As a
> 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 <email@example.com> -- 95855124