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++/
This archive was generated by hypermail 2b29 : Sat Jan 04 2003 - 23:51:03 MET