[Doc-SIG] Re: Ease of use is #1

Jack Jansen jack@oratrix.nl
Mon, 07 Feb 2000 23:21:18 +0100


Recently, Moshe Zadka <moshez@math.huji.ac.il> said:
> While I admire the way you markup by "guessing", I must admit I have my
> qualms about this approach: too little control for the documenter.
> Possibly, a mix of the two approaches is in order.

I think I agree with this. Now that I've seen the wonderful stuff Ping 
can do it may indeed be worthwhile to try and get more than simple
help-notes out of docstrings (as was my previous position:-).

It would be nice to be able to somehow override the guessing when you
(the author) know that it's wrong. Examples of this are mapping of
foo() in the text to a certain foo() in the code, but there are
probably many others (one that comes to mind is generated methods, as
in xmllib.py).

From the html-source and the comments at the bottom it appears that
there is an intermediate form, so that would be a nice place to hook
on to....
--
Jack Jansen             | ++++ stop the execution of Mumia Abu-Jamal ++++
Jack.Jansen@oratrix.com | ++++ if you agree copy these lines to your sig ++++
www.oratrix.nl/~jack    | see http://www.xs4all.nl/~tank/spg-l/sigaction.htm