Subject: Re: Documenting the AbiWord Program
From: Saint-Denis (stdenisg@cedep.net)
Date: Sun Dec 24 2000 - 09:11:39 CST
The "doxygen" documentation program could probably be of some help and bring
an easy solution to generate documentation in different formats. It support
documentation in the code header file, code file or in external file. The
program is available at http://www.stack.nl/~dimitri/doxygen/
Gilles
----- Original Message -----
From: Randy Kramer <rhkramer@fast.net>
To: <abiword-dev@abisource.com>
Sent: Saturday, December 23, 2000 1:35 PM
Subject: Re: Documenting the AbiWord Program
> (Dom and Jesper, thanks for the responses!)
>
> What about an approach using Exuberant Tags (or some hyperlinking
> approach)? I've never used tags (or Vim, Vi, or Emacs), but maybe I
> could put "newbie" level comments in a file that would be
> cross-referenced and easy to jump to by the use of tags. (I don't know
> tags, so partially I'm asking if tags make such an approach feasible.)
>
> Then, maybe, any newbie comments can be always accessible but out of the
> main flow of the program, and also always associated with the right
> location in the code? (Wherever it may move as long as the variable,
> object, or method name stays the same?)
>
> My impression is that a tag can "automagically" link to, for example a
> variable or object name. I wonder if there is a way to link a tag to a
> variable or object (or method) in a specific file, to distinguish
> between comments about the creation of a variable, object, or method,
> vs. comments about the usage of a variable, object, or method in a
> particular place in the code?
>
> Or, maybe I can assume that whenever a variable, object, or method is
> used, it is used to create some other entity, and I should tie my
> comments to the creation of that entity rather than the usage of
> entities in that object or method?
>
> Am I headed in a direction that might be sensible?
>
> Randy Kramer
>
> Dom Lachowicz wrote:
> >
> > 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 : Sun Dec 24 2000 - 09:12:13 CST