[jboss-user] [Microcontainer] - Re: Tool for documenting MC beans

[david.lloyd@jboss.com]

"jesper.pedersen" wrote : All I'm asking for here is a tool that can allow a project to document the MC beans they want to expose to other developers - or in case they don't have an up-to-date users guide to the end user.

That's the error, right there.  There should be zero such beans.

There are a few types of usable APIs in an MC environment: publicly documented Java APIs and annotations (which both are documented via Javadoc), and publicly documented XML descriptors (which appear as XSD and their associated docs).

Even if a class is designed to be used by a "bean" tag on a strictly internal basis (not that I would condone even that), the Javadoc of that class is sufficient to document it.  Adding another layer is purely redundant.

And by the way, TLD is a very poor example as the capabilities it provides are designed to document tags, not specific instances of tags.  For example, you could have a TLD which describes, say, the "bean" tag, but what good would that do you?  There are already documentation annotations on the bean-deployer XSD which do the same thing.

This whole notion is basically flawed.  Any effort is much better spent creating SchemaResolverDeployers for any services that currently do not have it, rather than shoring up an already less-than-optimal situation.


View the original post : http://www.jboss.org/index.html?module=bb&op=viewtopic&p=4230910#4230910

Reply to the post : http://www.jboss.org/index.html?module=bb&op=posting&mode=reply&p=4230910