> -----Original Message-----
> From: checkstyle-devel-admin@...
> [mailto:checkstyle-devel-admin@... Behalf Of Scott
> Sent: Wednesday, 18 September 2002 11:55
> To: checkstyle-devel@...
> Subject: RE: [Checkstyle-devel] Self-documentation of checks
> Oliver Burn said:
> > 2) The documentation for each individual Check. This documentation will
> > be produced by lots of different people. The desire is that we have a
> > structure that people follow. From which it is very easy to
> > generate the documentation for the check and to have it incorporated
> > into the general site.
> > I was thinking about tools that support some kind of structure and xbook
> > came to mind. Never used it, but I like the idea.
> > Personally I think that we should be looking to Maven
> All of these solutions (xbook, doclet and Maven) can use XML as the
> source, and I think that would be the most flexable format. I also think
> that unless you parse the docs right out of the method signatures of the
> Checks, you're going to have some level of abstraction and place some
> level of burden on the Check authors. I'm not real keen on parsing it
> right from the source simply because I don't think we'll be able to get
> enough information about how to use it without requiring the author to add
> _some_ formatted comments, and at that point I'd argue that you might as
> well go whole-hog and make the entire block (or external file) formatted
> XML. We could create an Ant task to validate their doc against a DTD
> defining all of the nodes and attributes required to auto-generate good
> documentation, so it should be easy (for them and us) to QA their work.
> If we use XML, I think it'd be pretty much a crap shoot as to which
> rendering tool we use, be it XSL, xbook, a custom doclet, or even Maven
> (although I'm cautious about that one because it's written by the
> extremely smart but complex Turbine crowd). In any case, I think we just
> need to keep in mind that the end product should be something _really_
> easy for a Check developer to conform to, as well as something we don't
> have to spend a abundant amount of time setting up and maintaining. To
> that point, I might be leaning slightly towards an external "xxxCheck.xml"
> and a doclet or XSL to render it.
I agree with you. Best to keep it simple.
Re Maven, they are certainly a talented bunch. I am cautious of Maven till
a version 1.0 is released and it is not so volatile. I figure that then
it is worth investigating what is in there.