C-Source Code as documentation (was Re: Doxygen use)

[David Lawyer <dave@lafn.org>]

On Thu, Nov 02, 2000 at 08:44:01AM -0700, Kevin Cullis wrote:
> Hi all,
> 
> Has anyone used Doxygen for use in LDP stuff?  Here's the web site:

How can it be used with LDP documents?  The site says that one may
'abuse' doxygen for creating normal documentation but why would we do
this?  Doxygen seems to be something that makes programming code (such as
C) more understandable.  It can generate analysis of the C-code in an
HTML document.
> 
> http://www.stack.nl/~dimitri/doxygen/
> 
> I'm trying to convince programmers to do a better job of documenting
> their code to make it easier for interested parties to latch on to
> their work and that by making code comments and using Doxygen, it
> could encourage participation of new people.
> 
I can always add comments inside of <!-- my-comment --> in the
LinuxDoc source.  Are you suggesting that readers would want to the
the author's comments (if any)?  But there is a good use for something
like doxygen and LDP can get involved if people  want to spend a lot
of time on it.  Here's why and how we could use it.

There are many undocumented (and inadequately documented) aspects of
Linux.  Sometimes people must read source code as the documentation of
last resort.  Many people can't do this since they don't know
programming but some can.  Looking over C-source has a double
advantage in that one might discover the cause of a bug.  I've
searched in vain for listings of the source code for Linux (the kernel
and all applications) as html documents on the Internet.  I've
sometimes found obsolete versions. 

So, if someone wants to do it, there's a big project of converting the
C-source code to HTML and putting it on the Internet.  The doxygen
generated documents might help too.  It needs to be kept updated to
the latest versions, but some people need to see old versions as well
as the most recent.  In addition, the default configuration files for
various distributions of Linux should be on-line.

Another project is improving the comments in the source code.  It may
be hard to convince programmers to do this since it's seemingly more 
important to fix bugs and make the program work properly than to
document what is happening in detail.

			David Lawyer


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org