Subject: Re: Documenting the AbiWord Program
From: Dom Lachowicz (cinamod@hotmail.com)
Date: Sat Dec 23 2000 - 12:47:45 CST
This sounds great. For various reasons, I was thinking of just having the
specs in ABW format. If someone would like to redo my docs in another
fashion afterwords, I'd be all for that.
Dom
>From: Randy Kramer <rhkramer@fast.net>
>To: abiword-dev@abisource.com
>Subject: Re: Documenting the AbiWord Program
>Date: Sat, 23 Dec 2000 13:35:32 -0500
>
>(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
>
_________________________________________________________________
Get your FREE download of MSN Explorer at http://explorer.msn.com
This archive was generated by hypermail 2b25 : Sat Dec 23 2000 - 12:47:47 CST