On Wed, 19 Jul 2000 21:21:50 -0400 Flemming Videbaek <videbaek@sgs1.hirg.bnl.gov> wrote: > Hi (particular Christian) > > While having just lost the beam and looking up some info in the BRAT > html web page I saw a problem (noticed) before with the pages. Several > classes do not map nicely to the ROOT doc extraction. Take as an (random > --hm!) example BrAppIntOption The class description is the CVS LOG > information - not very useful. Quite a few other do the same. Hmm, picking a (random?!) class, say BrDb, it actually does work. I made the the class documentation in exactly the say way as for BrAppIntOption, with one subtle difference! As you probably know, the first NON-EMPTY comment block in the implementation file (actually, the one with ClassImp(<class>)) is what gets put into the class description, NON-EMPTY being the operate word here. If you look in base/src/BrAppOption.cxx, you'll see the following lines (I've inserted <RET> litterally here): //<RET> // Command line option <RET> //<RET> <RET> //<RET> // $Id: BrAppOption.cxx,v 1.1 2000/04/06 20:17:41 cholm Exp $<RET> // $Author: cholm $<RET> // $Date: 2000/04/06 20:17:41 $<RET> // $Copyright: BRAHMS Collaboration 2000<RET> // <RET> // $Log: BrAppOption.cxx,v $ <RET> // Revision 1.1 2000/04/06 20:17:41 cholm<RET> // Added the classes BrAppOption, BrAppOptionManager, and<RET> // BrDetectorList. The first two are for command line processing,<RET> // the third for easy detector list, can be used for many purposes.<RET> Now notice the first line. It's an empty comment for "//". Then notice the line between "// $Copyright ..." and "// $Log ..." - that line isn't an empty comment line (at least not in THtml's eyes), since it contains a space character. To THtml this marks the beginning of the first NON-EMPTY comment block, and so what ever comes next is the class description i.e., the CVS log. The solution should be obvious. The first three lines should be // <RET> // Command line option <RET> //<RET> or even // Command line option <RET> //<RET> <RET> One can actually exploit this seemingly stupid feature of THtml. Suppose all your files must contain a copyright notice, say because the collaboration demands it; obviously you don't want the same copyright notice in documentation of all classes. Hence you start of the comment block containing the coipyright notice, with an empty comment line "//<RET>"!!! > To imprve this what should be done ? For other reasons I have suggested > to have the $log at the end > this is though not the real story- in other modules the $authors hsow up > etc. So we need a clarification of the ground rule to get good > documentation. I think I've answered that above, save the reason why I put a blank line between the class description and the CVS keywords, and why I use the CVS keywords. Last thing first: Exploiting the automatic pattern recognition of THtml, I have the lines Root.Html.Author: // $Author: Root.Html.LastUpdate: // $Date: Root.Html.Copyright: // $Copyright: Root.Html.HomePage: http://www.rhic.bnl.gov/brahms in my ~/.rootrc file; so that THtml will put some valid info on the bottom of the generated HTML page. Note that the "$Copyright$" keyword, really isn't a CVS keyword. I just used it for consistency. Now for the first thing: Putting a blank lline between the class description and the CVS keywords, ends the class description right there, since THtml only uses the FIRST non-empty comment block; and obviuosly I don't want the same info to appear twice. Finally, I agree that the "$Log$" keyword should go at the end of the file, since some of these logs are getting very long! Hope that clarifies a few things. Yours, Christian ----------------------------------------------------------- Holm Christensen Phone: (+45) 35 35 96 91 Sankt Hansgade 23, 1. th. Office: (+45) 353 25 305 DK-2200 Copenhagen N Web: www.nbi.dk/~cholm Denmark Email: cholm@nbi.dk
This archive was generated by hypermail 2b29 : Thu Jul 20 2000 - 05:48:49 EDT