Re: generating a manual from annotations in source code

[Maciej Stachowiak <mstachow@mit.edu>]

jimb@red-bean.com writes:
> 
> Did you ever read over the Java class documentation in the early days
> of Java?  They had it on the web.  It was terrible.  You couldn't
> figure anything out.  That's one example I have of a manual extracted
> from docstrings.  I also know that Stallman was quite opposed to the
> idea, and over the years I decided he was probably right.
> 

It definitely sucked, but I think we can do better. I think the main
reason it sucked was because it was organized solely be the class
names and package hierarchy, rather than in any logical way. I mean,
if I knew the name of the class I wanted and the package it was hiding
in, I probably didn't really need the manual that much anyway.

Another problem is that there was only a reference manual, and no
decent user manual providing task-oriented examples.

> It's just a gut feeling.  If you don't agree, you don't agree, and
> you should go with your own gut feeling.
> 

I trust your experience in this area, and I agree with many of your
specific concerns. But I also think we have a way of addressing some
of them, and I think the benefit is worth it.


> 
> Or, if you think it is valuable to have the text mingled with the
> source code, add a notation to your manual format that says "extract
> the docstring for this function from the source, and insert it here."
> That way, the layout of the source has no influence on the layout of
> the manual.
> 

Well, I don't think the layout of the source should dictate the layout
of the manual, for the reasons you cited. As I said before, I think
the hierarchy of the manual needs to be externally imposed, because,
as you said, the program's logical layout will not necessarily match
the manual's. If documentation of code implemented in C and in Scheme
need to be combined in one place, for instance, there's no possible
way to restructure the program to get this in one file.

However, I am not sure something as extreme as writing a manula
skeleton with special notations to extract the specific documentation
is necessary. Perhaps it is, and if it comes to that, I still think it
is a superior solution to extracting docstrings from the manual, for
the reasons below.

> 
> Do people feel that, if the documentation is a separate file,
> programmers will be discouraged from writing docs, whereas, if the
> documentation were mingled with the source, then programmers would
> naturally write docstrings as they go along?

This is the primary motivation to me. First, it helps get the manual
off the ground in the first place. If I look at the old outdated
crufty manual, I think "It sure will be a lot of work to get this to
match the current code." But if I can incrementally add docstrings and
get continually improving documentation as a result, I'll be a lot
more motivated. 

I think it also makes maintenance of the docs a more automatic
thing. It makes the transaction cost of updating the docs when you
change the program much lower, and it makes it a lot easier to
remember to do so (and perhaps makes you feel guilty when you don't),
since all the surrounding code will be annotated already.

The problem of coming up with a good manual _structure_ starting with
all this point documentation is not triviall, but I think it is well
worth the effort.

 - Maciej