[Doc-SIG] A couple quick comments
Edward D. Loper
edloper@gradient.cis.upenn.edu
Sat, 16 Jun 2001 08:21:19 EDT
I haven't had as much time as I wanted to work on docstring stuff
lately. But a couple quick comments:
1. I think we should try to concentrate on building a markup
language for docstrings. I think that trying to create a
general-purpose markup language, which is simple and easy and
wonderful etc., is going to be too hard of a project. We'll make
more progress if we just try to concentrate on docstrings.
2. Given that I would almost never use sections in a docstrings, I
don't really care how we do sectioning, or if we have it at all.
But I suggest we not exhaust too much of our energy on it..
3. I think we should try to direct some energy at figuring out the
details of the DPS. If we're to accept David's proposed
approach, then markup decisions should be made pretty far down
the road: first we create the DPS, then we construct a number of
actual markups, so we can play with them and try them out, and
*then* we'll have more experience with which to make decisions
about which markup features we want. If all my playing with
different docstring markups has taught me anything, it's that
there can be very subtle consequences to decisions you make about
the markup. I won't be happy accepting any argument about
whether X or Y is "better" until I can really try them both out
in the context of everything else we've decided.
4. I don't see a good reason to specify the interfaces used between
DPS pieces using DOM. Using/manipulating DOM can be much more of
a pain than using/manipulating Python objects. I think that we
should define a set of classes for representing documentation
(which would basically have a 1-to-1 correlation with a DTD).
These classes should implement a toDOM() method (or some such),
and maybe even have a fromDOM() type function.. I think it's
much more convenient to say things like::
myclassdoc.methods()[3]
than::
myclassdoc.findElements("method")[3].data
or whatever it would be in DOM (sorry, it's been a little while).
Anyway, that's all the time I have for now. I'm glad to see so much
activity on the sig again.
-Edward