JDoc makes the header files totally unreadable with all the comments. I
strongly prefer the comments in the source file. Also every change in
the implementation would force a change in the header to update the
comments and trigger complete recompiles. That is why we made THtml and
the source comments as they are. It would be nice if doxygen could be
made to understand the current ROOT doc style (description + first
consecutive comment field at the beginning of each method.
Cheers, Fons.
On Mon, 2002-08-05 at 13:13, Christian Holm Christensen wrote:
> Hi Alexandr,
>
> On 02 Aug 2002 16:38:01 +0200
> Alexandr Malusek <Alexandr.Malusek@imv.liu.se> wrote
> concerning "[ROOT] THtml & W3C validation":
> > Hi,
> >
> > I've noticed that HTML documentation produced by the THtml class
> > doesn't pass the W3C validation test (http://validator.w3.org/), see
> > e.g. http://validator.w3.org/check/?uri=http%3A//root.cern.ch/root/htmldoc/THtml.html
> > I'm sorry if this is a known problem.
>
> This is a know problem, but I don't recall it being said on this list
> though, so you're right to bring it up.
>
> Currently, there's very little to do about it. Rene, Axel Naumann,
> and myself have been discussion various options for how to improve the
> HTML documentation generator (THtml), and we've sort of come up with a
> few scenarios:
>
> 1) Rewrite THtml to do a lot more, like inheritance trees, user
> hooks, CSS, and so on. This is a bit tricky, as it requires
> making a C++ parser and scanner, which is doable, but takes some
> work.
>
> 2) Leave THtml as it is (more or less) for compatibility, and then
> use some other documentation system, like DoxyGen [1], Doc++ [2],
> or what not.
>
> Comments on this are welcome (after all, that's one of the things this
> list is for - discussion of where ROOT should go).
>
> My personal recommendation:
>
> Use JDoc-like documentation comments and use DoxyGen and/or Doc++. A
> possible rewrite of THtml _must_ support that kind of documentation.
> If you don't know what JDoc documentation looks like, here's a short
> example:
>
> /** This is the Foo class brief description ending in a period.
> Here comes the detailed description.
> */
> class Foo : public Bar {
> private:
> /// A brief-only description of a member.
> Int_t fInteger;
> /** Another brief description of a member.
> This time we have some more details too. */
> Float_t fFloatingPoint;
> public:
> /** Constructor.
> This shows how to document member function arguments (THtml
> can't do that).
> @param integer An integer argument.
> @param floatingPoint A floating point (real) argument. */
> Foo(Int_t integer, Float_t floatingPoint);
> /** Get the floating point number stored in object.
> We can also document return values:
> @returns the stored floating point. */
> Float_t GetFloatingPoint() const { return fFloatingPoint; }
> // This is a real comment, and _not_ a documentation string.
> ClassDef(Foo,0) // This comment is sort of obsolete with JDoc
> };
>
> DoxyGen allows you to put the documentation in the implementation file
> if you wish to, but it's not supported by all tools (e.g., Doc++):
>
> /// @class Foo.
> /// @brief This is the Foo class brief description ending in a period.
> /// Here comes the detailed description.
>
> /// @fn Foo::Foo(Int_t integer, Float_t floatingPoint);
> /// @brief Constructor.
> /// This shows how to document member function arguments (THtml
> /// can't do that).
> /// @param integer An integer argument.
> /// @param floatingPoint A floating point (real) argument. */
> Foo::Foo(Int_t integer, Float_t floatingPoint)
> : fInteger(integer), fFloatingPoint(floatingPoint)
> {}
>
> /// @fn Float_t Foo::GetFloatingPoint() const
> /// @brief Get the floating point number stored in object.
> /// We can also document return values:
> /// @returns the stored floating point. */
>
> Also, DoxyGen has the ability to output LaTeX, Postscript and
> Hyperlinked PDF (via LaTeX), HTML, and Windoze Help (`compiled' HTML)
> files, as well as providing loads of other features. IMHO it's _the_
> tool for documenting OO code.
>
> Yours,
>
> ____ | Christian Holm Christensen
> |_| | -------------------------------------------------------------
> | | Address: Sankt Hansgade 23, 1. th. Phone: (+45) 35 35 96 91
> _| DK-2200 Copenhagen N Cell: (+45) 24 61 85 91
> _| Denmark Office: (+45) 353 25 305
> ____| Email: cholm@nbi.dk Web: www.nbi.dk/~cholm
> | |
>
> [1] http://www.stack.nl/~dimitri/doxygen/
> [2] http://www.zib.de/Visual/software/doc++/
--
Org: CERN, European Laboratory for Particle Physics.
Mail: 1211 Geneve 23, Switzerland
E-Mail: Fons.Rademakers@cern.ch Phone: +41 22 7679248
WWW: http://root.cern.ch/~rdm/ Fax: +41 22 7679480
This archive was generated by hypermail 2b29 : Sat Jan 04 2003 - 23:51:03 MET