Documentation generation

[Eirik Nygaard]

On Sun, Oct 19, 2003 at 09:47:48AM +0100, Hiten Pandya wrote:
> David Cuthbert wrote:
> >Matthew Dillon wrote:
> >
> >>    I don't think we want to integrate document generation into the 
> >>source
> >>    code.  The problem is that you can't get too wordy without making the
> >>    source unreadable, and the result are usually definitions so 
> >>sparse as
> >>    to be useless for understanding any serious API.
> >
> >
> >Yeah, Doxygen (and JavaDoc) both result in code that's more sparse than 
> >I care for, making it more difficult for maintainers.  For users of the 
> >code, though, the indices and cross-reference tables that result are 
> >quite valuable.
> 
> 	I would rather prefer documenting the necessary/important
> 	functions by hand in a DragonFly Kernel Handbook, which keeps
> 	things clean, and also allows detailed explanations.
> 
> 	Regards,
> 

I agree with Hiten. It would be better to document the necessary functions
by hand in a some kind of a handbook and perhaps use it together with a
source code tag system. http://www.gnu.org/software/global/global.html is
nice, it can also make web pages for you so you can like to it from the
handbook.

-- 
Eirik Nygaard
eirikn at xxxxxxxxxxxx
Attachment:
pgp00000.pgp
-------------- next part --------------
A non-text attachment was scrubbed...
Name: pgp00000.pgp
Type: application/octet-stream
Size: 187 bytes
Desc: "Description: PGP signature"
URL: <http://lists.dragonflybsd.org/pipermail/kernel/attachments/20031019/5944b624/attachment-0020.obj>