Subject: Re: Documenting the AbiWord Program
From: Dom Lachowicz (cinamod@hotmail.com)
Date: Fri Dec 22 2000 - 15:43:00 CST
Hi Jesper, Randy and others,
No promises, but I hope to have something tangible for you guys over the
break. Our existing documentation is *way* out of date. And if it means that
more people will start hacking at the code, then that's great. I plan on
starting by reviewing what's been written and then cranking out docs one
module at a time.
Dom
>From: Jesper Skov <jskov@redhat.com>
>To: AbiWord-dev <abiword-dev@abisource.com>
>Subject: Re: Documenting the AbiWord Program
>Date: 22 Dec 2000 22:35:28 +0100
>
> >>>>> "Randy" == Randy Kramer <rhkramer@fast.net> writes:
>
>Randy> * Add comments aimed at several different levels of reader /
>Randy> programmer.
>
>This is difficult to achieve since all the comments should appear in
>the code "in situ".
>
>Hm... Maybe use a special syntax for very verbose comments, a la:
>
> /*V ... */
>
>And people who don't want to look at very verbose comments can use
>syntax highlighting to tone down anything matching that pattern.
>
>Randy> * Do the commenting in such a fashion that it can easily be
>Randy> updated when the program is modified, and that, if it is not
>Randy> updated, it is immediately obvious that the comments are out of
>Randy> date.
>
>I think most experienced programmers would agree that the most useful
>form of documentation is a short primer to the function / construct
>that describes input/output and how the magic works. Very low-level
>details are best left documented in the form of code - after all,
>expresing the program flow is best done with strict language semantics
>rather than vague "human" explanations.
>
>Of course, some functions use very powerful magic, and it may not be
>immediately obvious even to an experienced programmer what's going
>on. In that case a few helpful comments throughout the code comes in
>handy (and assertions are even better - again avoiding confusion on
>account of being strictly logical).
>
>Randy> PS: I don't mean to imply that the AbiWord program is not
>Randy> adequately documented. It may be very adequately documented
>Randy> for a proficient C++ programmer. It is not adequate for me as
>Randy> a newbie. (I downloaded some earlier version of the code,
>Randy> perhaps 0.7.8, and tried to understand it. In the new year, I
>Randy> intend to try again.)
>
>It certainly isn't so well commented that some average hacker like
>myself can start hacking without spending some serious (i.e., too
>much) time reading the code.
>
>I feel that we need more documentation of stuff "as seen from
>20000-feet" - there are a few .abw documents and a single .html
>document on some of the design issues, but it's painfully lacking for
>thickheaded people like myself.
>
>I have also considered suggesting adding DocBook function descriptions
>in the same way as Alan Cox started doing it for the Linux kernel,
>allowing us to generate a document with APIs and general descriptions
>of the various components and how they interact.
>
>I hope to get to spend some time after Xmas walking the walk instead
>of just talking the talk, starting to understand and document the
>fmt/ptbl backend code... But we'll see. I'll probably end up wasting
>my time on other stuff...
>
>Jesper
>
_________________________________________________________________
Get your FREE download of MSN Explorer at http://explorer.msn.com
This archive was generated by hypermail 2b25 : Fri Dec 22 2000 - 15:43:02 CST