Menu
▾
▴
corelinux-develop
|
From: Frank V. C. <fr...@co...> - 2000-11-15 14:56:11
|
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. 2. By including all the source code and all the headers, documentation is growing and is redundant. Thoughts? |
|
From: Christophe Prud'h. <pru...@an...> - 2000-11-15 15:10:01
|
On Wednesday 15 November 2000 14:57, you wrote: > 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. > 2. By including all the source code and all the headers, documentation > is growing and is redundant. > > Thoughts? change the doxygen configuration file do not include headers and source code I don't remember the exact name of the options but you should be able to find it easily (look for SOURCE/CODE and HEADER) C. -- Christophe Prud'homme MIT -- 77 Mass Ave 02215 Cambridge MA |
|
From: Frank V. C. <fr...@co...> - 2000-11-15 15:24:13
|
Christophe Prud'homme wrote: > On Wednesday 15 November 2000 14:57, you wrote: > > 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. > > 2. By including all the source code and all the headers, documentation > > is growing and is redundant. > > > > Thoughts? > change the doxygen configuration file > do not include headers and source code > I don't remember the exact name of the options but you should be able to find > it easily (look for SOURCE/CODE and HEADER) What about the syntax of using /*! */ in the headers? BTW: It is my intent to open this for discussion, not to abolish. I was pointing out the downsides. Is there a happy medium? > > > C. > -- > Christophe Prud'homme > MIT -- 77 Mass Ave > 02215 Cambridge MA > _______________________________________________ > Corelinux-develop mailing list > Cor...@li... > http://lists.sourceforge.net/mailman/listinfo/corelinux-develop |
|
From: Christophe Prud'h. <pru...@an...> - 2000-11-15 15:40:56
|
I was thinking about the inclusion of the source code + headers in the html doc. > What about the syntax of using > /*! > */ > > in the headers? is it at the very beginning of the file with the \file flag, or for macro documentation? normally the doxygen specific flags appear when there is no javadoc equivalent if not then I made a mistake I think that doxygen introduces some interesting features that enables to extract relevant and useful informations depending on the context. if it happens that javadoc is extended then it is likely that doxygen provides a similar feature then it is just a matter of modifying the tag(perl script) and I guess that the doxygen team will try to implement the new javadoc features. > > BTW: It is my intent to open this for discussion, not to abolish. I was > pointing out the downsides. Is there a happy medium? that is a good one I think :) -- Christophe Prud'homme MIT -- 77 Mass Ave 02215 Cambridge MA |
|
From: Hans - D. <dul...@eg...> - 2000-11-15 15:26:05
|
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 |
|
From: Frank V. C. <fr...@co...> - 2000-11-15 18:14:20
|
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 |
|
From: Hans - D. <dul...@eg...> - 2000-11-15 21:57:02
|
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 |
|
From: Christophe Prud'h. <pru...@an...> - 2000-11-15 15:47:31
|
Another comment about source documentation : normally doxygen strips out the documentation from the source file when it creates the html source code. so that the source code is more readable. if not then that is bad and clearly redundant with the extracted and generated doc ! Ijsut checked my debian corelinux doc and the documentation is removed by doxygen before creating the corresponding html file However some comments don't disappear like the GNU LICENSE and non javadoc/doxygen comments best regards C. -- Christophe Prud'homme MIT -- 77 Mass Ave 02215 Cambridge MA |
