Re: [Corelinux-develop] Comments and documentation

[Hans - D. <dul...@eg...>]

On Wed, 15 Nov 2000, Frank V. Castellucci wrote:

> Date: Wed, 15 Nov 2000 13:18:21 -0500
> From: Frank V. Castellucci <fr...@co...>
> Reply-To: cor...@li...
> To: cor...@li...
> Subject: Re: [Corelinux-develop] Comments and documentation
> 
> With Christophe's comments and yours we can begin to weed through this
> jungle
> 
> I think that we should only add the magical doxygen tags in the header
> files where we need to use what JavaDoc does not provide, for macros,
> enums, etc. 
> 
> By doxygen specific I mean those tags that have:
> 
> /*!
> */
> 
> instead of
> 
> /**
> */
> 
> And Hans, I meant consistent with the CoreLinux++ comment style
> 
> As far as the source inclusion, I believe the inclusion of header and
> source files in the documentation is overkill and redundant as the
> curious user can download the tarball which has the real thing!
>

Oh..., I misunderstood your point. Now, I understand that what you mean
is the inclusion of the TEXT of the source code/headers. In this case, I
agree with you. The TEXT of the source code/headers should not be
included. I believe Doxygen can be configured to replace them with a
hyperlink instead.

I thought you meant inclusion/exclusion of source codes in Doxygen search
path controlled by the INPUT, FILE_PATTERNS, EXCLUDE, and EXCLUDE_PATTERNS
Doxygen options.
 
> Most programmers reference don't include the source code in the
> reference or the headers, what I am familiar with is a general
> description with a method by method break down. Some example code to
> emphasize usage, and an overview (which will become very important in
> the frameworks).
> 
> More thoughts?
> 

-- 
Hans Dulimarta, Ph.D.                  dul...@co...
P: 517-432-7589             http://www.egr.msu.edu/~dulimart   
F: 760-281-7691             http://corelinux.sourceforge.net
Elec. & Comp. Engg., Mich. State Univ., E. Lansing, MI 48824