[Doc-SIG] Evolution of library documentation

Edward D. Loper edloper@gradient.cis.upenn.edu
Tue, 13 Mar 2001 18:07:45 EST


> Well, a reference manual is sometimes at a higher level than what I put
> in docstrings. But maybe I should be prefixing more methods with '_'.

It may make sense to have some place other than docstrings for reference
manual docs, if someone chooses to use it.  But I think that docstrings
could give a very good "default" reference manual entry.  Of course,
I tend to be very thorough in my commenting & documenting. :)

> > I think that we should leave the organization of "grander scope"
> > documentation to a different project..  (Of course, it's still
> > an important project.)
> 
> Yes, yes, yes (indeed, I thought that's what was already being done,
> quietly in the background, by our Mr Drake)

Good to hear.

> (the whole issue of how one
> quotes things in ST is a difficult one, single quote itself is enough of
> a problem. The "true ST" approach, I think, is to say "borderline case -
> punt it - we're not that complex", which *may* well be the correct
> answer).

I don't see why it has to be a difficult issue, but hopefully someone
will explain it to me. :)  But I disagree that the "true ST" approach
is to say "borderline case - punt it."  I think that's the approach
of most *current implementations* of ST, not of ST itself.  If ST is
to become accepted and useful, we *do* need to define borderline cases,
or at least make them explicitly undefined.  It really sucks to try
to use a language/markup that keeps changing under your feet, and is
inconsistant between tools. :)

> BUT whilst I don't mind reserving it, I'll probably oppose using it!
> (but allowing you to reserve it postpone the argument, which is a Very
> Good Thing, and it gives us a *marker* for having postponed the
> argument)

Hm.. so unless anyone objects, we'll reserve it for now, with the 
understanding that it may become unreserved later, or it may become
meaningful..

> STpy is almost as complex as I want it to get already - I want to add in
> [references] and then feature freeze. Which would have become clear in
> the alpha (he whines)

I'm still unclear about this [references] thing; explain it?
But I do agree that ST is complex enough.  (btw, why do we need
3 different unordered list bullets?  That seemed like enormous
overkill to me, and getting rid of 'o' as a bullet would solve
some problems with foreign languages..  Any chance that we could
just standardize on *either* '*' or '-'?  I guess the STNG people
won't like that though...)

> Well, actually it's "Arguments". And the special meaning isn't
> *enforced* in the current implementation or documentation, but it may be
> in the future (so much to do, so little whatever).

I think of arguments as values you give a function, and parameters
as the slots to receive them.  But I mainly chose "parameters" to
be consistant with javadoc etc.  Doesn't really matter to me what
we call it.

> >   author -- Edward Loper
> >   version -- 2.71828
> 
> That's::
> 
> 	Author: Edward Loper
> 	Version: 2.71828
> 
> and it doesn't work yet (because '<keyword>:' doesn't yet start a
> paragraph) - it may or may not work in the alpha release.

As I argued in a previous email, I really think it should be description
list items, but I'll wait for you to argue your case.. :)

> > Then you just have to worry about syntax for inline markup.  I don't
> > have any great ideas there, other than having a whole class of
> > "advanced inline markup" tags like @somethingorother(...)
> 
> Given the '@' reserved, we can leave that...

Agreed.  Any further inline markup will be left for another day.

-Edward