checkstyle

All,
   Please whack me if a thread is already started on this - I just joined
the list :-).  What are the current thoughts about documenting Checks? 
Oliver said something about XDOCS, and I've found more info about it at
http://www.justobjects.org/xbook/ .  Apparently you can invoke an
optional <xbook> ant task, which would potentially make release
documentation a breeze to generate.  Shall I start studying xbook or do
you have a path already in mind?  Are there advantages and
disadvantages aready identified for xbook vs. other approaches?
   Scott

Scott McCrory wrote:

>All,
>   Please whack me if a thread is already started on this - I just joined
>the list :-).  What are the current thoughts about documenting Checks? 
>Oliver said something about XDOCS, and I've found more info about it at
>http://www.justobjects.org/xbook/ .  Apparently you can invoke an
>optional <xbook> ant task, which would potentially make release
>documentation a breeze to generate.  Shall I start studying xbook or do
>you have a path already in mind?  Are there advantages and
>disadvantages aready identified for xbook vs. other approaches?
>   Scott
>
Hi Scott,

I don't really know what I'm talking about, haven't used xbook or 
doclets yet, but...

Judging from the web page, xbook might be a good start, especially for 
more general documentation like "how do I start checkstyle", "how do I 
write a check", etc.

For the individual checks that checkstyle provides, it just occurred to 
me that an xbook input file would basically duplicate the Javadoc class 
documentation of the individual checks (right?). Wouldn't it make more 
sense to extract the javadoc using a doclet? We're also pretty good at 
parsing Java, so we might want to create our own doc extraction tool ... :-)

The main point is that such an approach would keep code and 
documentation in one file, with all the advantages we know from javadoc.

just a thought,
Lars

> Judging from the web page, xbook might be a good start, especially for
> more general documentation like "how do I start checkstyle", "how do I
> write a check", etc.

That's possible.  I will say though that my initial impressions are that
it might take a good bit of time to (re)write the docs in raw XML so that
the xbook could use it natively.  On the other hand, xbook might be useful
for its pagination features, and we could use existing HTML pages for the
content (it will do that too).  I guess the thing I like about documenting
user stuff in HTML is that it's so darned easy and familiar, and I really
like the current layout of Checkstyle's web site and documentation. 
Redoing it for xbook doesn't seem real beneficial to me yet, but I'm open
to ideas.

> For the individual checks that checkstyle provides, it just occurred to
> me that an xbook input file would basically duplicate the Javadoc class
> documentation of the individual checks (right?). Wouldn't it make more
> sense to extract the javadoc using a doclet? We're also pretty good at
> parsing Java, so we might want to create our own doc extraction tool ...
> :-)
> Lars

True, it would be more straightforward to embed the documentation in the
JavaDoc.  We could "force" Check writers to follow a standard
documentation template in their class javadoc, either as embedded HTML or
a little more formatted using custom tags and a custom doclet like you
suggest.  I really like the way Check documentation is currently
displayed, and it might be possible to match that format using javadoc,
custom tags and a custom doclet.
   Scott

I agree that there are two types of documentation:

1) The general site documentation including the how-tos on running
   Checkstyle and developing checks. This is stuff that we produce, so
   hence we can do whatever makes sense and it does not need to be
   highly structured.

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
(http://jakarta.apache.org/turbine/maven/) to see how they have solved the
problem. They supply general document
(http://jakarta.apache.org/turbine/maven/reference/user-guide.html) and
also documentation for the plug-ins
(http://jakarta.apache.org/turbine/maven/reference/plugins/index.html).

Regards,
Oliver

> -----Original Message-----
> From: checkstyle-devel-admin@...
> [mailto:checkstyle-devel-admin@... Behalf Of Scott
> McCrory
> Sent: Wednesday, 18 September 2002 05:55
> To: checkstyle-devel@...
> Subject: Re: [Checkstyle-devel] Self-documentation of checks
> 
> > Judging from the web page, xbook might be a good start, especially for
> > more general documentation like "how do I start checkstyle", "how do I
> > write a check", etc.
> 
> That's possible.  I will say though that my initial impressions are that
> it might take a good bit of time to (re)write the docs in raw XML so that
> the xbook could use it natively.  On the other hand, xbook might be useful
> for its pagination features, and we could use existing HTML pages for the
> content (it will do that too).  I guess the thing I like about documenting
> user stuff in HTML is that it's so darned easy and familiar, and I really
> like the current layout of Checkstyle's web site and documentation. 
> Redoing it for xbook doesn't seem real beneficial to me yet, but I'm open
> to ideas.
> 
> > For the individual checks that checkstyle provides, it just occurred to
> > me that an xbook input file would basically duplicate the Javadoc class
> > documentation of the individual checks (right?). Wouldn't it make more
> > sense to extract the javadoc using a doclet? We're also pretty good at
> > parsing Java, so we might want to create our own doc extraction tool ...
> > :-)
> > Lars
> 
> True, it would be more straightforward to embed the documentation in the
> JavaDoc.  We could "force" Check writers to follow a standard
> documentation template in their class javadoc, either as embedded HTML or
> a little more formatted using custom tags and a custom doclet like you
> suggest.  I really like the way Check documentation is currently
> displayed, and it might be possible to match that format using javadoc,
> custom tags and a custom doclet.
>    Scott

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.
   Scott

> -----Original Message-----
> From: checkstyle-devel-admin@...
> [mailto:checkstyle-devel-admin@... Behalf Of Scott
> McCrory
> 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.
>    Scott
> 

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.

Regards,
Oliver

> 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.
>
> Regards,
> Oliver

Keep in mind that this is just ONE approach, but a relatively
straightforward one at that:  If we had the Check authors create not just
MyCheck.java, but also MyCheck.xml, then we could use Ants "style" task to
transform each one into a pretty (and standardized) HTML manual page using
a standard check.xsl.  This would work very similar to Stephane Bailliez'
checkstyle-noframes.xsl, and in fact perhaps she is the best one to write
chack.xsl if she's still available.  I was thinking that the raw data
could be stored as such:

<?xml version='1.0' encoding='utf-8' standalone='no'?>
<!--
 Documentation source file for a Checkstyle "Check" - is used to
 automatically generate the HTML documentation.
-->
<check>

  <!-- Basic Check information -->
  <category>Imports</category>
  <name>AvoidStarImport</name>
  <description>Determines improper usage of star (*) imports</description>
  <date>20020918</date>
  <authorName>Oliver Burns</authorName>
  <authorEmail>oliver@...>

  <!-- Options that this Check makes use of -->
  <option>
    <name>allowStarImports</name>
    <description>Set to true if you want to allow star imports</description>
    <default>false</default>
  </option>

  <!-- Examples of this Check's usage - more is better! -->
  <example>
    <name>Example 1</name>
    <description>Enables the flagging of star imports</description>
    <body>Blah blah blah</body>
  </example>

  <example>
    <name>Example 2</name>
    <description>Disables the flagging of star imports</description>
    <body>Blah blah blah</body>
  </example>

</check>

There would also be a corresponding check.dtd to make sure the docs are
well-formed.  What do you think?
   Scott