[Doc-SIG] field syntax (was re: lists & blank lines)

[Edward D. Loper]

> [Edward Loper]
> >     3. The field list must be the last thing in a docstring
> 
> Why? What about PEPs?

I've been trying to design a ML for formatted docstrings; if it works
for other domains, great, if not, too bad.  I don't want to impede
progress because we're trying to solve a more general problem than
we really need to.

> > I require the contents of each directive
> > to be indented.
> 
> Why? And what do you mean by "directive" here? (Note that my proposed
> directive syntax was for arbitrary language extension. The keyword-tagged
> values directive was just an example.)

Why: so we know when they end.

I think we may be talking about 2 different things here, though, and
that may be a stumbling block.  The functionality that I want is
basically what JavaDoc implements with "@tags".  I've used JavaDoc,
and other similar systems for other programming languages, and it
is *very* useful.  E.g., it lets you have a little "section" to describe
each parameter, the return value, etc.  I'm not sure that this is
the same thing that you're calling "keyword-tagged values."  Maybe
it is..  But I'd like to be able to say something semantically 
equivalant to::

   @param elt The initial element.
   @param n The size of the list.

in my docstrings for functions/methods.  Also, I'd like to be able to
include multiple paragraphs, lists, etc., in the description of a
parameter.

> > Note that you are not required to start a paragraph
> > on the line that a list bullet is on.. You can write list items 
> > like this if you want::
> >     1. 
> >        Paragraph one for list item (1).
> > 
> >        Paragraph two for list item (1).
> 
> I'm confused. So what? And why would we want this?

If it confuses you, ignore it; it's not really important.

> > The only other difference would be that, under my scheme, the contents
> > of a directive have to be properly formatted formatted text; where
> > under your scheme it seems like they can be anything.
> 
> Not "anything", but directive-dependent. 

Yes.  But from the parser's point of view, it can be anything, because
it doesn't know what extensions you'll be using.  Some later stage
(after the parser) will put restrictions on it..

> > This is a feature that I'm very interested in making sure that the
> > markup language includes.
> 
> Keyword-tagged values have been discussed in the past on Doc-SIG. If they're
> that important to you, I'd suggest you go through the archives, list up all
> proposed alternatives, analyze & summarize. Otherwise, history repeats.

I've been going through the archives, on and off, and haven't seen
that many *different* proposals that deal with what I'm trying to do..
But I guess I'll keep looking.  

> > I see this feature as being more 
> > important than the ability to use lists or colorizing..)
> 
> I don't. Everyone has their own agenda, their own priorities. Beware that
> yours don't become a stumbling block for others' acceptance. :)

Fine, as long as we all agree that our main agenda is to develop a
markup language for use with docstrings.

> One problem with getting a Setext/StructuredText derivative to satisfy
> everyone's needs is that the more characters we use as markup, the more
> complex it becomes. 

Which is one of the reasons I'm trying to get as much milage out of
indentation as I can.. :)

> Another is that the available characters are limited.

True.  Although, it's not a character we're taking away.  It's the
ability to start a paragraph with "@\w+\b".  Just like bullets, the @
will be treated as @ in any other circumstance.

> Are keyword-tagged values important enough to warrant the use of another
> character for their syntax? Edward's answer is obviously "yes". 

I believe that having keyword-tagged values, or whatever we want to
call them, is worth removing the ablity to start paragraphs with
"@\w+\b".

> Mine was "no" (also because "@" isn't obvious/intuitive)

The obvious/intuitive reason seems better to me, although I don't see
starting paragraphs with ".." as being any more intuitive.. The problem
is that if you use something intuitive, like::

    author: Edward Loper
    param size: The radius of the planet, in miles

Then you're much more likely to prevent people from saying things they
want to say, like::

    However: ...

> and so I proposed a general explicit solution to future extension.

Which may be a good thing (although I would argue that directives should
end on a return to the indentation that introduced them, esp. since this
is consistant with the other use of "::")..  

But I think that these "keyword-tagged values" are central enough 
to the task of writing docstrings (especially for functions and 
methods; but also for describing class variables, etc) that they 
can be given their own syntax.. (Well, not quite their own -- 
they're really just lists with funny looking bullets that must 
appear at the top level and at the end of the docstring)

-Edward