Re: [Corelinux-develop] Comments and documentation

[Frank V. C. <fr...@co...>]

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!

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 wrote:
> 
> On Wed, 15 Nov 2000, Frank V. Castellucci wrote:
> 
> > Date: Wed, 15 Nov 2000 09:57:20 -0500
> > From: Frank V. Castellucci <fr...@co...>
> > Reply-To: cor...@li...
> > To: CoreLinux Development <cor...@li...>
> > Subject: [Corelinux-develop] Comments and documentation
> >
> >
> > Christophe introduced a new form of documentation for code (headers and
> > modules).
> >
> > A couple of issues with this
> >
> > 1. It is not consistent with the majority of the code and makes
> > readability a problem.
> 
> Do you mean the majority of the code in our corelinux project
> or majority of the code in other projects as well?
> 
> > 2. By including all the source code and all the headers, documentation
> > is growing and is redundant.
> 
> I think there should be two different kinds of manual: user's guide and
> programmer reference. What we have now is a programmer reference manual,
> which is usually huge in size. For completeness we should not leave out
> any source code at all but to minimize redundancy trimming the doxygen
> comments in our source codes might be necessary.
> 
> >
> > Thoughts?
> >
> > _______________________________________________
> > Corelinux-develop mailing list
> > Cor...@li...
> > http://lists.sourceforge.net/mailman/listinfo/corelinux-develop
> >
> 
> --
> 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
> 
> _______________________________________________
> Corelinux-develop mailing list
> Cor...@li...
> http://lists.sourceforge.net/mailman/listinfo/corelinux-develop

-- 
Frank V. Castellucci
http://corelinux.sourceforge.net
OOA/OOD/C++ Standards and Guidelines for Linux
http://PythPat.sourceforge.net
Pythons Pattern Package