I'd been working on my own version of a tool to document the schema on
nights and weekends when Tim submitted his to the list. After cursing
him for stealing my thunder, I took a look at his hoping to find some
synergy between the two efforts. I've borrowed some ideas from his tool
and after too many after hours hackathons, I've come up with something
I'm reasonably pleased with. Attached is a new asadmin command I've
written to generate some documentation of the schema at runtime. It
will generate some html and css files in the config directory next to
domain.xml. All you should need to do is drop the jar into your modules
directory and restart glassfish. (Apparently new commands aren't
recognized without a restart despite all the osgi goodness involved.)
To run it, simply type:
asadmin create-documentation
The default (and only) output format at the moment is the HTML format.
I'm planning on adding dtd and xsd support for those needing validation
for their domain.xml files. What is also *not* currently supported are
subclasses of config elements that might conceivable end up having xml
nodes associated with them (I'm thinking of things like the jruby
container stuff) but I'm planning on adding that some evening.
Anyway. Try it out if you'd like. If you have questions, please feel
free to ask. I'm going to put the source up on kenai.com unless
everyone wants this in the v3 tree directly (my preference, personally)
and I'll let you know when that goes up for those wanting the source.
The html code isn't the prettiest at the moment but it's loosely based
on the javadoc styles and is good enough for a first pass.
A few quick comments and then maybe I'll finally let myself go to bed
(past midnight here):
* While the deprecated classes/elements are indicated, I don't
currently have a way to track deprecated methods/attributes on non
deprecated classes/elements. I don't know if that's currently an
issue but it's not hard to imagine that coming up sooner or later.
* I don't bother displaying the property descriptions on deprecated
classes since they're not used. I suppose I could similarly hide
the attributes of deprecated elements as well...
* You'll notice that some classes have property descriptions and
some don't even though those classes have properties that are
used. If you haven't documented the getProperty() method on your
interface with the @PropertiesDesc annotation, there's no way to
tell that those properties exist much less any detail about them.
* Similarly, you may notice that some properties are listed that are
no longer supported. In this case, you'll want to delete that
property from the props array in the PropertiesDesc annotation for
that interface.
* This is a work in progress done in snatches of time here and
there. Suggestions are welcome but please be gentle. ;)