[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