From: Dmitri G. <gri...@gm...> - 2009-06-21 02:05:50
|
Hello list, After I started looking at Qt driver source I noticed that it lacked a consistent coding style. So, I decided to fix it up. In process of making this patch I discovered some more problems, but unfortunately they are not coding style problems (for example, very similarly looking blocks of code). I didn't try to address those now, but I will after this patch will get into svn. I understand that coding style is a very subjective matter, so I'm open for discussion. I just want the code to be readable and have consistent style. I attach two versions of patch: the patch itself and patch for review. The reason for that is that the patch is basically "delete everything and insert the following". Patch for review was generated using diff -B -b -w which ignores all whitespace changes. Also I attach a file with coding style example (a short source with all possible language constructs). Regards, Dmitri -- main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if (j){printf("%d\n",i);}}} /*Dmitri Gribenko <gri...@gm...>*/ |
From: Alan W. I. <ir...@be...> - 2009-06-21 17:38:06
|
On 2009-06-21 05:04+0300 Dmitri Gribenko wrote: > I understand that coding style is a very subjective matter, so I'm > open for discussion. I just want the code to be readable and have > consistent style. Hi Dmitri: Thanks for bringing up this topic. With so many contributors over the 17 years of development, I suspect PLplot currently has no consistent coding style either for C or C++. So it's probably an overall issue that we have a chance to solve here rather than just for the qt device driver alone. I think most here would agree with the goal of a readable and consistent style for our C and C++ code, but the trick is to find some consensus that everybody is willing to go along with. I have no strong opinions about what that consensus should be, but once we have arrived at it, I think we should make it as easy as possible for emacs users to conform to that convention. Several of our core developers have been using emacs for a long time, and I am a recent enthusiastic convert (after using jed for a decade). So let me ask a question of the expert emacs users here. Once we come to consensus on the style, is it possible to put some boilerplate comments in our C and C++ source code so that emacs automatically conforms to that style? Or is that better done with some emacs customization style changes in .emacs that can be selected as the "PLplot" style on the fly by emacs users? Alan __________________________ Alan W. Irwin Astronomical research affiliation with Department of Physics and Astronomy, University of Victoria (astrowww.phys.uvic.ca). Programming affiliations with the FreeEOS equation-of-state implementation for stellar interiors (freeeos.sf.net); PLplot scientific plotting software package (plplot.org); the libLASi project (unifont.org/lasi); the Loads of Linux Links project (loll.sf.net); and the Linux Brochure Project (lbproject.sf.net). __________________________ Linux-powered Science __________________________ |
From: Geoffrey F. <Geo...@at...> - 2009-06-26 03:44:16
|
Alan W. Irwin writes: > On 2009-06-21 05:04+0300 Dmitri Gribenko wrote: > > > I understand that coding style is a very subjective matter, so I'm > > open for discussion. I just want the code to be readable and have > > consistent style. > > Hi Dmitri: > > Thanks for bringing up this topic. With so many contributors over the 17 > years of development, I suspect PLplot currently has no consistent coding > style either for C or C++. So it's probably an overall issue that we have a > chance to solve here rather than just for the qt device driver alone. > > I think most here would agree with the goal of a readable and consistent > style for our C and C++ code, but the trick is to find some consensus that > everybody is willing to go along with. > > I have no strong opinions about what that consensus should be, but once we > have arrived at it, I think we should make it as easy as possible for emacs > users to conform to that convention. Several of our core developers have > been using emacs for a long time, and I am a recent enthusiastic convert > (after using jed for a decade). > > So let me ask a question of the expert emacs users here. Once we come to > consensus on the style, is it possible to put some boilerplate comments in > our C and C++ source code so that emacs automatically conforms to that > style? Or is that better done with some emacs customization style changes > in .emacs that can be selected as the "PLplot" style on the fly by emacs > users? I would recommend that we publish a plplot-style that works with CC mode in [X]Emacs. Then the question is how that style is selected. There is some trick involving file-local Emacs variables, which we could look up. An alternative that I have used for some years, is something I call "infer-style", which figures out which style to use for a file based on where it sits. This way it makes it easy for me to work on multiple projects which use different styles, with no tweaking of my Emacs config, and no messy file-local variables in the files in all the projects. If we get as far as adopting a specific style for PLplot, I would be happy to share my Elisp hooks and doohickies with others. As for specific suggestions on the elements of style, just to get some specifics out for consideration, I suggest: 1) No tabs. Tabs are evil. Spaces only. 2) 4 spaces per indent level 3) Liberal use of spaces: This: if ( a != 0 && ( b == 2 || c == 2 - x ) ) ... rather than: if(a!=0&&(b==2||c==2-x)) ... 4) Braces: if ( condition ) { ... } else { ... } 5) Focus on language rules rather than "code-nany" style rules. For example, to me, this is okay: if ( condition ) single_line_action(); else ... The part between the if and the else does not require enclosure in braces, even though GCC 4.4 now whines about that in -Wall mode. 6) Somewhat controversial, but I actually do think warning free code is, to an extent, a matter of style. If we would agree to seek the elimination of all warnings from GCC 4.4 -Wall, for instance, then I would agree to style rules that I might not otherwise be excited about (like the one mentinoed above). I would also be interested in standardizing function comment blocks. There are a number of differntly styled function intro blocks evident in PLplot. One thing I've been doing in my professional projects of late, is using doxygen. I find the standard doxygen style that depends on all the '*' characters to be really ugly, but since I mostly code in C++, there is the alternative of ///, which annoys me, but not as badly as " * ", plus those dorky header/trailer tokens. I've not tried doxygen on a C code base before, so I'm not sure if there are options that are more visibly appealilng than the standard/default. Without looking into it a bit first, I'm not in a postion to propose a specific style for function comment blocks. But I thought I throw out the doxygen option in case anyone else is interested in that, and able to summarize some of the options. Fundamentally, I like the 79-char horizontal separators for functions. I think that makes the code a lot easier to read. But I'm very annoyed by the /* ... */ style of multi-line C comments. Did C99 pick up //-style comment to end of line? If so, what would people think of using that in our C code base? Another element of style that Maurice and I have both used for nearly two decades now, is that in-function comments are out-dented one level. We've met some vi users who complain about this, but for [X]Emacs folk, it's trivially easy to configure the cc-mode to do this, so that it requires no extra keystrokes, and just happens automatically (plus end-of-line auto wrapping support). Especially combined with font locking, it really helps to make comments stand out in a way that lets you easily and visually separate the control logic and the comments thereupon. Unfortunately we can't do that (out-denting of comments) in Python, due to the indentation-as-structure-definition semantic of the language. But I think it's probably basically inevitable that there will necessarily be at least some minor variations in adapting a style to a variety of languages. Well, those are some of my initial thoughts in regard to Alan's comments. -- Geoff |
From: Maurice L. <mj...@br...> - 2009-06-28 20:30:59
|
Agree with Geoff's comments on style with one caveat and one addition. The caveat concerns out-denting of comments: I basically drop my advocacy of this. I still tend to prefer it, but find that (a) others generally don't like it, and (b) a custom color for comments does (almost) the same job of making them stand out sufficiently from the following code. So I'm fine with either out-denting or not. The addition concerns line length -- I think 80 chars is too restrictive but we also don't want any 150 character long monstrosities either (I would've thought the latter goes without saying but I've seen it, not in plplot tho). Keeping it less than something like 100 chars would be a good goal. -- Maurice LeBrun |
From: Andrew R. <and...@us...> - 2009-06-26 21:46:50
|
Geoff, This sounds an eminently sensible set of coding guidelines and close to what I would have suggested. I have only a couple of comments (see below). In general I don't have really strong feelings about these things. I would like consistency though. As long as we can easily configure emacs to "do the right thing" I personally would be happy. Andrew On Thu, Jun 25, 2009 at 10:44:09PM -0500, Geoffrey Furnish wrote: > > I would recommend that we publish a plplot-style that works with CC mode in > [X]Emacs. > > Then the question is how that style is selected. There is some trick > involving file-local Emacs variables, which we could look up. > > An alternative that I have used for some years, is something I call > "infer-style", which figures out which style to use for a file based on where > it sits. This way it makes it easy for me to work on multiple projects which > use different styles, with no tweaking of my Emacs config, and no messy > file-local variables in the files in all the projects. > > If we get as far as adopting a specific style for PLplot, I would be happy to > share my Elisp hooks and doohickies with others. > > As for specific suggestions on the elements of style, just to get some > specifics out for consideration, I suggest: > > 1) No tabs. Tabs are evil. Spaces only. > 2) 4 spaces per indent level > 3) Liberal use of spaces: > > This: > > if ( a != 0 && ( b == 2 || c == 2 - x ) ) ... > > rather than: > > if(a!=0&&(b==2||c==2-x)) ... > All agreed. > 4) Braces: > > if ( condition ) > { > ... > } > else > { > ... > } I have a slight personal preference for: if ( condition ) { ... } else { ... } but I'm happy to live with the consensus. > 5) Focus on language rules rather than "code-nany" style rules. > For example, to me, this is okay: > > if ( condition ) > single_line_action(); > > else > ... > > The part between the if and the else does not require enclosure in braces, > even though GCC 4.4 now whines about that in -Wall mode. > 6) Somewhat controversial, but I actually do think warning free code is, to > an extent, a matter of style. If we would agree to seek the elimination > of all warnings from GCC 4.4 -Wall, for instance, then I would agree to style > rules that I might not otherwise be excited about (like the one mentinoed > above). I don't see anything wrong with this code, but as a general rule I would agree that it is better to be warning free if possible. This makes the compile neater and reduces bug reports. > I would also be interested in standardizing function comment blocks. There > are a number of differntly styled function intro blocks evident in PLplot. > > One thing I've been doing in my professional projects of late, is using > doxygen. I find the standard doxygen style that depends on all the '*' > characters to be really ugly, but since I mostly code in C++, there is the > alternative of ///, which annoys me, but not as badly as " * ", plus those > dorky header/trailer tokens. > > I've not tried doxygen on a C code base before, so I'm not sure if there are > options that are more visibly appealilng than the standard/default. Without > looking into it a bit first, I'm not in a postion to propose a specific style > for function comment blocks. But I thought I throw out the doxygen option in > case anyone else is interested in that, and able to summarize some of the > options. > > Fundamentally, I like the 79-char horizontal separators for functions. I > think that makes the code a lot easier to read. But I'm very annoyed by the > /* ... */ style of multi-line C comments. Did C99 pick up //-style comment > to end of line? If so, what would people think of using that in our C code > base? I tend to think the /*********************** * Function name * Description ***********************/ style of comment is a little fiddly to write, but is very readable and clearly marks out different functions. In recent years we have tended to stamp out the use of // comments in non-C++ code since it is not standard. If your using emacs with font lock mode then either is easy to read, so I suggest we stick with the traditional C style for maximum compatibility. > Another element of style that Maurice and I have both used for nearly two > decades now, is that in-function comments are out-dented one level. We've > met some vi users who complain about this, but for [X]Emacs folk, it's > trivially easy to configure the cc-mode to do this, so that it requires no > extra keystrokes, and just happens automatically (plus end-of-line auto > wrapping support). Especially combined with font locking, it really helps to > make comments stand out in a way that lets you easily and visually separate > the control logic and the comments thereupon. Again, this is not something I usually do, but I can see the sense in it. > Unfortunately we can't do that (out-denting of comments) in Python, due to > the indentation-as-structure-definition semantic of the language. But I > think it's probably basically inevitable that there will necessarily be at > least some minor variations in adapting a style to a variety of languages. > > Well, those are some of my initial thoughts in regard to Alan's comments. No rules will fit all languages I suspect, and some will have their own coding style anyway. We can at least make the core code, drivers and C / C++ examples consistent and apply this to other languages where appropriate. Andrew |
From: Hezekiah M. C. <hez...@us...> - 2009-06-28 23:32:10
|
My votes/comments are below. I generally use vim so I prefer vim-friendly guidelines. I hope that doesn't affect my standing in the PLplot community :-) On Fri, Jun 26, 2009 at 2:03 PM, Andrew Ross<and...@us...> wrote: > On Thu, Jun 25, 2009 at 10:44:09PM -0500, Geoffrey Furnish wrote: >> 1) No tabs. Tabs are evil. Spaces only. >> 2) 4 spaces per indent level >> 3) Liberal use of spaces: >> >> This: >> >> if ( a != 0 && ( b == 2 || c == 2 - x ) ) ... >> >> rather than: >> >> if(a!=0&&(b==2||c==2-x)) ... >> > > All agreed. I agree as well. (3) may have a little too much whitespace for my taste. I think this reads more easily: if (a != 0 && (b == 2 || c == 2 - x)) ... That said, I am far happier with either of these than the "rather than" example above. >> 4) Braces: >> >> if ( condition ) >> { >> ... >> } >> else >> { >> ... >> } > > I have a slight personal preference for: > > if ( condition ) { > ... > } > else { > ... > } > > but I'm happy to live with the consensus. I agree with Andrew on this. >> 5) Focus on language rules rather than "code-nany" style rules. >> For example, to me, this is okay: >> >> if ( condition ) >> single_line_action(); >> >> else >> ... >> >> The part between the if and the else does not require enclosure in braces, >> even though GCC 4.4 now whines about that in -Wall mode. > >> 6) Somewhat controversial, but I actually do think warning free code is, to >> an extent, a matter of style. If we would agree to seek the elimination >> of all warnings from GCC 4.4 -Wall, for instance, then I would agree to style >> rules that I might not otherwise be excited about (like the one mentinoed >> above). > > I don't see anything wrong with this code, but as a general rule I would > agree that it is better to be warning free if possible. This makes the > compile neater and reduces bug reports. I again agree with Andrew on this. >> I would also be interested in standardizing function comment blocks. There >> are a number of differntly styled function intro blocks evident in PLplot. >> >> One thing I've been doing in my professional projects of late, is using >> doxygen. I find the standard doxygen style that depends on all the '*' >> characters to be really ugly, but since I mostly code in C++, there is the >> alternative of ///, which annoys me, but not as badly as " * ", plus those >> dorky header/trailer tokens. >> >> I've not tried doxygen on a C code base before, so I'm not sure if there are >> options that are more visibly appealilng than the standard/default. Without >> looking into it a bit first, I'm not in a postion to propose a specific style >> for function comment blocks. But I thought I throw out the doxygen option in >> case anyone else is interested in that, and able to summarize some of the >> options. >> >> Fundamentally, I like the 79-char horizontal separators for functions. I >> think that makes the code a lot easier to read. But I'm very annoyed by the >> /* ... */ style of multi-line C comments. Did C99 pick up //-style comment >> to end of line? If so, what would people think of using that in our C code >> base? > > I tend to think the > > /*********************** > * Function name > * Description > ***********************/ > > style of comment is a little fiddly to write, but is very readable and clearly > marks out different functions. In recent years we have tended to stamp out the > use of // comments in non-C++ code since it is not standard. If your using > emacs with font lock mode then either is easy to read, so I suggest we stick > with the traditional C style for maximum compatibility. Agreed. >> Another element of style that Maurice and I have both used for nearly two >> decades now, is that in-function comments are out-dented one level. We've >> met some vi users who complain about this, but for [X]Emacs folk, it's >> trivially easy to configure the cc-mode to do this, so that it requires no >> extra keystrokes, and just happens automatically (plus end-of-line auto >> wrapping support). Especially combined with font locking, it really helps to >> make comments stand out in a way that lets you easily and visually separate >> the control logic and the comments thereupon. > > Again, this is not something I usually do, but I can see the sense in it. I would prefer not to do this. As Maurice comments in his reply, syntax highlighting handles this quite nicely. >> Unfortunately we can't do that (out-denting of comments) in Python, due to >> the indentation-as-structure-definition semantic of the language. But I >> think it's probably basically inevitable that there will necessarily be at >> least some minor variations in adapting a style to a variety of languages. >> >> Well, those are some of my initial thoughts in regard to Alan's comments. > > No rules will fit all languages I suspect, and some will have their own > coding style anyway. We can at least make the core code, drivers and C / > C++ examples consistent and apply this to other languages where appropriate. I think, where appropriate, the standards within each of the supported PLplot languages should hold. "Where appropriate" is probably best determined by the author(s) of each language binding. Sticking as close as possible to the feel of the core PLplot standards is probably best. A line length of 80 characters is a fairly common standard. I do not think that it needs to be a hard rule, but I find that it helps keep up readability in the general case. Should a standard convention for naming functions/values/macros be set? For example, most of the PLplot C functions are prefixed by "pl", but a few have a "pl_" prefix. Similarly, the spelling of function names range noticeably in their verbosity. API growth will likely be slow, but a standard would be helpful. This has come up recently is in the HAVE_* name clashes. A standard naming scheme should help address questions like this. Hez -- Hezekiah M. Carty Graduate Research Assistant University of Maryland Department of Atmospheric and Oceanic Science |
From: Werner S. <sm...@ia...> - 2009-09-21 08:09:48
|
Hi, > > One thing I've been doing in my professional projects of late, is > using > doxygen. I find the standard doxygen style that depends on all the > '*' > characters to be really ugly, but since I mostly code in C++, there > is the > alternative of ///, which annoys me, but not as badly as " * ", plus > those > dorky header/trailer tokens. > > I've not tried doxygen on a C code base before, so I'm not sure if > there are > options that are more visibly appealilng than the standard/default. > Without > looking into it a bit first, I'm not in a postion to propose a > specific style > for function comment blocks. But I thought I throw out the doxygen > option in > case anyone else is interested in that, and able to summarize some > of the > options. Since I use myself doxygen a lot for my own code, I started to "doxyfy" the PLplot source code. I added a Doxygen configuration file and changed on source code file (plpage.c) so that Doxygen can filter the description for the functions. I copied the output of doxygen to the net: http://www.miscdebris.net/plplot_doxygen/ You need to click "File List" on the left and then "plpage.c" to see some source code documentation, since I chose to only add documention for functions with doxygen descriptions. I did that, since I regularly wander around the plplot core code not finding what I need and I know that doxygen makes that a lot easier with cross references and so on. Question is now, 1) if everybody agrees to "doxyfy" the plplot source code 2) if everybody agrees how I documented the functions If it's ok, then I start the doxyfying process and everybody else is welcome to join. Regards, Werner -- Dr. Werner Smekal Institut fuer Allgemeine Physik Technische Universitaet Wien Wiedner Hauptstr 8-10 A-1040 Wien Austria email: sm...@ia... web: http://www.iap.tuwien.ac.at/~smekal phone: +43-(0)1-58801-13463 (office), +43-(0)1-58801-13469 (laboratory) fax: +43-(0)1-58801-13499 |
From: Andrew R. <and...@us...> - 2009-09-21 08:49:51
|
On Mon, Sep 21, 2009 at 10:09:22AM +0200, Werner Smekal wrote: > Hi, > > > > One thing I've been doing in my professional projects of late, is > > using > > doxygen. I find the standard doxygen style that depends on all the > > '*' > > characters to be really ugly, but since I mostly code in C++, there > > is the > > alternative of ///, which annoys me, but not as badly as " * ", plus > > those > > dorky header/trailer tokens. > > > > I've not tried doxygen on a C code base before, so I'm not sure if > > there are > > options that are more visibly appealilng than the standard/default. > > Without > > looking into it a bit first, I'm not in a postion to propose a > > specific style > > for function comment blocks. But I thought I throw out the doxygen > > option in > > case anyone else is interested in that, and able to summarize some > > of the > > options. > > Since I use myself doxygen a lot for my own code, I started to > "doxyfy" the PLplot source code. I added a Doxygen configuration file > and changed on source code file (plpage.c) so that Doxygen can filter > the description for the functions. I copied the output of doxygen to > the net: > > http://www.miscdebris.net/plplot_doxygen/ > > You need to click "File List" on the left and then "plpage.c" to see > some source code documentation, since I chose to only add documention > for functions with doxygen descriptions. > > I did that, since I regularly wander around the plplot core code not > finding what I need and I know that doxygen makes that a lot easier > with cross references and so on. Question is now, > > 1) if everybody agrees to "doxyfy" the plplot source code > 2) if everybody agrees how I documented the functions > > If it's ok, then I start the doxyfying process and everybody else is > welcome to join. Werner, As a general principle I think this is a good idea and good coding practice. I've not used doxygen, although I am aware that it seems to be the "standard" for this kind of thing. The markup comment style is a little quirky, but I can live with that. I'll hold off any crustify changes to the code until we decide on this. At some stage (if we do this) it would be nice to generate at least some of the documentation using the same markup. This is likely to be non-trivial, but would save a huge amount of duplication, particularly in terms of function prototypes, arguments and return values. I've no idea if this is possible. Andrew |
From: Alan W. I. <ir...@be...> - 2009-09-21 17:34:32
|
On 2009-09-21 10:09+0200 Werner Smekal wrote: > Hi, >> >> One thing I've been doing in my professional projects of late, is using >> doxygen. I find the standard doxygen style that depends on all the '*' >> characters to be really ugly, but since I mostly code in C++, there is the >> alternative of ///, which annoys me, but not as badly as " * ", plus those >> dorky header/trailer tokens. >> >> I've not tried doxygen on a C code base before, so I'm not sure if there >> are >> options that are more visibly appealilng than the standard/default. >> Without >> looking into it a bit first, I'm not in a postion to propose a specific >> style >> for function comment blocks. But I thought I throw out the doxygen option >> in >> case anyone else is interested in that, and able to summarize some of the >> options. > > Since I use myself doxygen a lot for my own code, I started to "doxyfy" the > PLplot source code. I added a Doxygen configuration file and changed on > source code file (plpage.c) so that Doxygen can filter the description for > the functions. I copied the output of doxygen to the net: > > http://www.miscdebris.net/plplot_doxygen/ > > You need to click "File List" on the left and then "plpage.c" to see some > source code documentation > I did that, since I regularly wander around the plplot core code not finding > what I need and I know that doxygen makes that a lot easier with cross > references and so on. Question is now, > > 1) if everybody agrees to "doxyfy" the plplot source code > 2) if everybody agrees how I documented the functions > > If it's ok, then I start the doxyfying process and everybody else is welcome > to join. Hi Werner: I think this would be a superb and powerful replacement for our normal in-source documentation. I have a small amount of experience with doxygen via the libLASi project and was much impressed by it. Following your instructions above to refer to plpage (and the functions defined within that source code) confirmed just how useful this could be to us. I must emphasize this should be seen as excellent supplement to our already existing DocBook form of API documentation. doxygen is good at giving the quick details an experienced PLplot library developer needs plus all the important internal cross-references for our implementation. In contrast, our DocBook form of API documentation can be more general; it should be aimed more for external programmers who are using our API but who have no need to know about the internal details of our implementation of that API. So, yes please, go ahead as far as I am concerned with "doxygenating" our in-source documentation. However, I do have some further comments and suggestions. * We mostly do this already with our in-source documentation, but I wanted to mention the general principle of keeping the doxygen form of that documentation as short as possible for each of our functions (e.g., use one sentence rather than a paragraph to describe the function or one of its parameters). This documentation should be considered a short reminder aimed at experienced PLplot library developers and not something more comprehensive that you might expect from our DocBook form of API documentation. I think the current level of detail we have for plgspa (http://www.miscdebris.net/plplot_doxygen/plpage_8c.html#ac9d7c35262ab1c80cc1ed9bf15f7f128) is just about right. So this is not a criticism of what we have now. Instead, I just wanted to state the principle to be clear how this documentation potentially differs in brevity from the DocBook form of our API documentation. * For each of our functions please put in a cross-reference to the website form of documentation for that same function that is generated by DocBook in order to give everybody access to the broader overview that implies. * Currently those DocBook-generated URL's are in the versioned form http://plplot.sourceforge.net/docbook-manual/plplot-html-5.9.5/*.html. Regardless of how this doxygen project goes, I plan to change those URL's to the unversioned form, i.e., http://plplot.sourceforge.net/docbook-manual/plplot-html/*.html since it should help other websites as well as our doxygen-generated one to have a constant URL to refer to for our html documentation generated by DocBook. Anyhow, assume the unversioned form when doing the cross-references from the doxygenized code comments. * The URL's for the current form of our doxygen documentation are a mess (as can be seen from the form of plgspa URL above). Is there a configuration parameter to shorten those to something that is comprehensible (and thus guaranteed to be constant) such as .../plplot_doxygen/plpage.c_plgspa.html? I think we should cross-reference every doxygen function reference from our corresponding DocBook API documentation, but this is only practical with a non-changing form of URL for everything that doxygen documents. You may have that already, but a comprehensible URL without a bunch of random numbers in it is useful in many other ways as well. * Location. The generation of documentation in doxygen form should be part of our release tarball and also our SourceForge website. I would be happy to help out there by doing the appropriate changes to our build system and making an additional script to populate our website with the results. To move forward with this, please send me the doxygen commands you recommend to generate the html version of our doxygen results in our build tree. I can take it from there. Alan __________________________ Alan W. Irwin Astronomical research affiliation with Department of Physics and Astronomy, University of Victoria (astrowww.phys.uvic.ca). Programming affiliations with the FreeEOS equation-of-state implementation for stellar interiors (freeeos.sf.net); PLplot scientific plotting software package (plplot.org); the libLASi project (unifont.org/lasi); the Loads of Linux Links project (loll.sf.net); and the Linux Brochure Project (lbproject.sf.net). __________________________ Linux-powered Science __________________________ |
From: Werner S. <sm...@ia...> - 2009-09-21 19:20:01
|
Hi Alan, >> >> Since I use myself doxygen a lot for my own code, I started to >> "doxyfy" the >> PLplot source code. I added a Doxygen configuration file and >> changed on >> source code file (plpage.c) so that Doxygen can filter the >> description for >> the functions. I copied the output of doxygen to the net: >> >> http://www.miscdebris.net/plplot_doxygen/ >> >> You need to click "File List" on the left and then "plpage.c" to >> see some >> source code documentation >> I did that, since I regularly wander around the plplot core code >> not finding >> what I need and I know that doxygen makes that a lot easier with >> cross >> references and so on. Question is now, >> >> 1) if everybody agrees to "doxyfy" the plplot source code >> 2) if everybody agrees how I documented the functions >> >> If it's ok, then I start the doxyfying process and everybody else >> is welcome >> to join. > > Hi Werner: > > I think this would be a superb and powerful replacement for our normal > in-source documentation. I have a small amount of experience with > doxygen > via the libLASi project and was much impressed by it. Following your > instructions above to refer to plpage (and the functions defined > within that > source code) confirmed just how useful this could be to us. I must > emphasize this should be seen as excellent supplement to our already > existing DocBook form of API documentation. doxygen is good at > giving the > quick details an experienced PLplot library developer needs plus all > the > important internal cross-references for our implementation. In > contrast, > our DocBook form of API documentation can be more general; it should > be > aimed more for external programmers who are using our API but who > have no > need to know about the internal details of our implementation of > that API. That's exactly how I see the doxygen documentation too - as a supplement for the PLplot developer, not as a replacement for our existing DocBook documentation. > > So, yes please, go ahead as far as I am concerned with > "doxygenating" our > in-source documentation. However, I do have some further comments and > suggestions. > > * We mostly do this already with our in-source documentation, but I > wanted > to mention the general principle of keeping the doxygen form of that > documentation as short as possible for each of our functions > (e.g., use > one sentence rather than a paragraph to describe the function or > one of > its parameters). This documentation should be considered a short > reminder > aimed at experienced PLplot library developers and not something > more > comprehensive that you might expect from our DocBook form of API > documentation. I think the current level of detail we have for > plgspa > (http://www.miscdebris.net/plplot_doxygen/plpage_8c.html#ac9d7c35262ab1c80cc1ed9bf15f7f128 > ) > is just about right. So this is not a criticism of what we have > now. > Instead, I just wanted to state the principle to be clear how this > documentation potentially differs in brevity from the DocBook form > of our > API documentation. Agreed. > > * For each of our functions please put in a cross-reference to the > website > form of documentation for that same function that is generated by > DocBook > in order to give everybody access to the broader overview that > implies. > > * Currently those DocBook-generated URL's are in the versioned form > http://plplot.sourceforge.net/docbook-manual/plplot-html-5.9.5/*.html > . > Regardless of how this doxygen project goes, I plan to change > those URL's > to the unversioned form, i.e., > http://plplot.sourceforge.net/docbook-manual/plplot-html/*.html > since it > should help other websites as well as our doxygen-generated one to > have a > constant URL to refer to for our html documentation generated by > DocBook. > Anyhow, assume the unversioned form when doing the cross- > references from > the doxygenized code comments. Already added and will do from now on. > > * The URL's for the current form of our doxygen documentation are a > mess (as > can be seen from the form of plgspa URL above). Is there a > configuration > parameter to shorten those to something that is comprehensible > (and thus > guaranteed to be constant) such as > .../plplot_doxygen/plpage.c_plgspa.html? I think we should > cross-reference every doxygen function reference from our > corresponding > DocBook API documentation, but this is only practical with a non- > changing > form of URL for everything that doxygen documents. You may have > that > already, but a comprehensible URL without a bunch of random > numbers in it > is useful in many other ways as well. Agreed as well, but I didn't find any option yet - need to ask the Doxygen mailing list. > > * Location. The generation of documentation in doxygen form should > be part > of our release tarball and also our SourceForge website. I would > be happy > to help out there by doing the appropriate changes to our build > system and > making an additional script to populate our website with the > results. > To move forward with this, please send me the doxygen commands you > recommend > to generate the html version of our doxygen results in our build > tree. > I can take it from there. I don't know if it should be part of the relase tarball, since the documentation produced by doxygen is already 2.3Mb big - maybe because of the search function (index). So I'm not sure if it's fully documented, this just makes the release tarball much too big. The cmake build system should be no problem - in the moment you just need to run "doxygen" in the source tree - the documentation will be build in ./doc/code. Obviously the "Doxyfile" need to be copied to the build tree and "doxygen" run there. Searching the internet via google for "cmake doxygen" reveals some help about using doxygen with cmake (there is a package for it). > > Alan > __________________________ > Alan W. Irwin > > Astronomical research affiliation with Department of Physics and > Astronomy, > University of Victoria (astrowww.phys.uvic.ca). > > Programming affiliations with the FreeEOS equation-of-state > implementation > for stellar interiors (freeeos.sf.net); PLplot scientific plotting > software > package (plplot.org); the libLASi project (unifont.org/lasi); the > Loads of > Linux Links project (loll.sf.net); and the Linux Brochure Project > (lbproject.sf.net). > __________________________ > > Linux-powered Science > __________________________ > > ------------------------------------------------------------------------------ > Come build with us! The BlackBerry® Developer Conference in SF, CA > is the only developer event you need to attend this year. Jumpstart > your > developing skills, take BlackBerry mobile applications to market and > stay > ahead of the curve. Join us from November 9-12, 2009. Register > now! > http://p.sf.net/sfu/devconf > _______________________________________________ > Plplot-devel mailing list > Plp...@li... > https://lists.sourceforge.net/lists/listinfo/plplot-devel -- Dr. Werner Smekal Institut fuer Allgemeine Physik Technische Universitaet Wien Wiedner Hauptstr 8-10 A-1040 Wien Austria DVR-Nr: 0005886 email: sm...@ia... web: http://www.iap.tuwien.ac.at/~smekal phone: +43-(0)1-58801-13463 (office) +43-(0)1-58801-13469 (laboratory) fax: +43-(0)1-58801-13499 |
From: Alan W. I. <ir...@be...> - 2009-09-22 02:13:13
|
On 2009-09-21 21:18+0200 Werner Smekal wrote: > [...]The cmake build system should be no > problem - in the moment you just need to run "doxygen" in the source tree - > the documentation will be build in ./doc/code. It turns out you have to configure Doxyfile (its template is now called doc/Doxyfile.in) in order to get a build of our doxygen documentation to work properly in the build-tree. Also, I didn't like the doc/code name (I believe "code" is too generic) so I took the liberty of replacing it with doc/doxygen (to make it similar to doc/docbook). As of revision 10454 the build of our doxygen documentation (which only happens if you specify -DBUILD_DOX_DOC=ON) appears to be working well. Anyhow it generates 2.6MB of files in doc/doxygen in the build tree. If I run "make clean", doc/doxygen disappears like it is supposed to. When I copy those to a place where apache can publish them, the results look good with my konqueror browser, the search box works, etc. However, the results are different than those at http://www.miscdebris.net/plplot_doxygen. The search box is in a different place (and does not work for the misdebris version), and the locally generated version does not have "Data Structures". Is the miscdebris site out of sync with doc/Doxyfile.in? Anyhow, Werner, the doxygen generation seems to be working well in our build system, and I am looking forward to further doxygenation of our source code commentary now you have shown how to do it. Alan __________________________ Alan W. Irwin Astronomical research affiliation with Department of Physics and Astronomy, University of Victoria (astrowww.phys.uvic.ca). Programming affiliations with the FreeEOS equation-of-state implementation for stellar interiors (freeeos.sf.net); PLplot scientific plotting software package (plplot.org); the libLASi project (unifont.org/lasi); the Loads of Linux Links project (loll.sf.net); and the Linux Brochure Project (lbproject.sf.net). __________________________ Linux-powered Science __________________________ |
From: Alan W. I. <ir...@be...> - 2009-09-21 19:25:23
|
On 2009-09-21 09:49+0100 Andrew Ross wrote: > [...]The markup comment style is a little quirky, but I can live with that. I'll hold > off any crustify changes to the code until we decide on this. Hi Andrew: I am concerned we move forward with uncrustify soon so there will be plenty of time to test the full conversion results (and adjust if necessary by tweaks to uncrustify.cfg) before our next release. I think the uncrustify project is independent of Werner's doxygen project so the order of which gets done first doesn't matter that much. In fact, putting all our comments into a standard form with uncrustify would probably help Werner a bit. I presume he is converting the comments near the head of each function to doxygen form and it always easier to convert from one consistent form (rather than a grab-bag of forms). I just double-checked that doxygen-style comments and uncrustify are compatible. For your information there was a bug reported about that at http://sourceforge.net/tracker/?func=detail&aid=2792426&group_id=153164&atid=786647 but it turned out to be an artifact of non-zero indent_with_tabs. This should not be a problem for us since uncrustify.cfg sets indent_with_tabs to 0. Anyhow, I suggest you just go ahead with doing your last tweaks of uncrustify.cfg (if any more are necessary) to make sure Werner's plpage.c doxygen changes are preserved, and you are otherwise satisfied with the style. Then convert src and bindings/c++ to that standard style as a substantial proof-of-concept for C and C++ code which we can all evaluate before you do the full conversion of all our C and C++ code. That last step might have to be repeated with more minor tweaks to uncrustify.cfg, but it would be good to get at least one full iteration of this process done in the near future for the reasons I mentioned above. Alan __________________________ Alan W. Irwin Astronomical research affiliation with Department of Physics and Astronomy, University of Victoria (astrowww.phys.uvic.ca). Programming affiliations with the FreeEOS equation-of-state implementation for stellar interiors (freeeos.sf.net); PLplot scientific plotting software package (plplot.org); the libLASi project (unifont.org/lasi); the Loads of Linux Links project (loll.sf.net); and the Linux Brochure Project (lbproject.sf.net). __________________________ Linux-powered Science __________________________ |
From: Andrew R. <and...@us...> - 2009-09-22 14:52:42
|
On Mon, Sep 21, 2009 at 12:25:12PM -0700, Alan Irwin wrote: > On 2009-09-21 09:49+0100 Andrew Ross wrote: > > > [...]The markup comment style is a little quirky, but I can live with that. I'll hold > > off any crustify changes to the code until we decide on this. > > Hi Andrew: > > I am concerned we move forward with uncrustify soon so there will be plenty > of time to test the full conversion results (and adjust if necessary by > tweaks to uncrustify.cfg) before our next release. > > I think the uncrustify project is independent of Werner's doxygen project so > the order of which gets done first doesn't matter that much. In fact, > putting all our comments into a standard form with uncrustify would probably > help Werner a bit. I presume he is converting the comments near the head of > each function to doxygen form and it always easier to convert from one > consistent form (rather than a grab-bag of forms). > > I just double-checked that doxygen-style comments and uncrustify are > compatible. For your information there was a bug reported about that at > http://sourceforge.net/tracker/?func=detail&aid=2792426&group_id=153164&atid=786647 > but it turned out to be an artifact of non-zero indent_with_tabs. This > should not be a problem for us since uncrustify.cfg sets indent_with_tabs to > 0. > > Anyhow, I suggest you just go ahead with doing your last tweaks of > uncrustify.cfg (if any more are necessary) to make sure Werner's plpage.c > doxygen changes are preserved, and you are otherwise satisfied with the > style. Then convert src and bindings/c++ to that standard style as a > substantial proof-of-concept for C and C++ code which we can all evaluate > before you do the full conversion of all our C and C++ code. That last > step might have to be repeated with more minor tweaks to uncrustify.cfg, > but it would be good to get at least one full iteration of this process > done in the near future for the reasons I mentioned above. I have gone ahead and committed a uncrustified version of plpage.c. This does not seem to have affected the doxygen comments. The changes in this case were relatively minor suggesting that we have a good "style". The core code is on the whole far more uniform. If people are happy I will progress with the rest of src/ and bindings/c++. Andrew in coding style. It would be nice to bring the rest of the code into line. |
From: Alan W. I. <ir...@be...> - 2009-09-22 16:27:41
|
On 2009-09-22 15:52+0100 Andrew Ross wrote: > I have gone ahead and committed a uncrustified version of plpage.c. This > does not seem to have affected the doxygen comments. The changes in this > case were relatively minor suggesting that we have a good "style". The > core code is on the whole far more uniform. > > If people are happy I will progress with the rest of src/ and bindings/c++. When evaluating these style changes, I highly recommend using, e.g., http://plplot.svn.sourceforge.net/viewvc/plplot/trunk/src ==> plpage.c ==> Diff to previous. Those coloured diffs are great for clearly showing the changes, and I like what I see. Of course, others should judge for themselves, but the principal style issues for me are consistency and (now that my eyes aren't quite as good as they used to be) visual clarity via appropriate whitespace. I am happy those fundamental style goals are finally within our grasp at long last due to the power of uncrustify. Alan __________________________ Alan W. Irwin Astronomical research affiliation with Department of Physics and Astronomy, University of Victoria (astrowww.phys.uvic.ca). Programming affiliations with the FreeEOS equation-of-state implementation for stellar interiors (freeeos.sf.net); PLplot scientific plotting software package (plplot.org); the libLASi project (unifont.org/lasi); the Loads of Linux Links project (loll.sf.net); and the Linux Brochure Project (lbproject.sf.net). __________________________ Linux-powered Science __________________________ |