[Doc-SIG] Docstrings Format
Tue, 7 Nov 2000 10:05:05 +1100
> > 4. It must contain sufficient information so it can be converted
> > to any reasonable markup format.
> I disagree with "4": I cannot mark up things like "this is a Python
I am not with you here. Whether you agree or not about (4) seems quite
independent of the capability to add certain markups?
I agree with (4), but also agree with your requirement for that markup
> If you show me how to extend StructuredText for these
> kind of things, it would definitely get a chance.
I hate to tell you this Moshe, but I would speculate that the general
feeling on this SIG (assuming it hasnt changed over the last 12 months)
would be that StructuredText definitely has a chance regardless ;-)
> Please have a look at the PEP and see the exact markup goals
> I've outlined. Of course, if you do not agree with the goals,
> you can say that too...
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
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.
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. Without a specific markup proposal it doesn't seem to add much
of value, and as soon as you try and extend it to a specific markup
proposal, we are back in the exact same position as 6 months ago.
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
* 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.)
Pity-noone-asked-me-to-vote-though <winky> ly,