-
1. Re: Tool for documenting MC beans
dmlloyd May 13, 2009 12:12 PM (in response to jesper.pedersen)I think this approach is incorrect. Any jboss-beans.xml files that we include should be considered part of the private implementation of that service. A -beans.xml file is a script (a program) which is tied to implementation details of the service, like class structure, not a configuration file. As such, the appropriate way to document it is with plain XML comments.
Any time we are exposing a service configuration to users as XML, we should be using a separate descriptor format which doesn't depend directly on the class structure of the service. This is the only way that we can avoid configuration incompatibility between AS releases. A separate descriptor implies a schema file, which can be annotated with documentation in a way that is supported by most XML authoring tools and IDEs.
I recognize that we do currently have a lot of services using jboss-beans.xml as configuration; I think that rather than devoting effort to a documentation system, we ought to be busy creating descriptor formats for these services instead. -
2. Re: Tool for documenting MC beans
jason.greene May 13, 2009 12:18 PM (in response to jesper.pedersen)I agree that these definitions are internal implementation details, that change with the wind. If we treated them as an API, then we would have to ensure backward compatibility, and that would really restrict us.
I also agree that user configuration does not belong in our MC beans, that instead should be relegated somewhere else. Potentially this could be the which is also used for the ProfileService persistence mechanism. -
3. Re: Tool for documenting MC beans
jesper.pedersen May 13, 2009 12:42 PM (in response to jesper.pedersen)There are two level of users here.
1) End users
2) Other developers inside JBoss
End users should hopefully never see the jboss-beans.xml files - but that is the case today unless you plan to fix that.
The foundation of our projects should be the MC, but if there isn't any documentation for the MC beans available each project will start to code duplicated functionality. Asking Ales in the forum each time a bean is needed doesn't scale. Period.
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.
Kabir, an example of how TLD documentation looks like http://www.jboss.org/file-access/default/members/jbossrichfaces/freezone/docs/tlddoc/index.html
AS is a black box in how services (interfaces, properties, ...) are exposed and glued together - and I don't see a developer guide explaining that happening any time soon. -
4. Re: Tool for documenting MC beans
dmlloyd May 13, 2009 1:02 PM (in response to jesper.pedersen)"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. -
5. Re: Tool for documenting MC beans
jesper.pedersen May 13, 2009 1:09 PM (in response to jesper.pedersen)David, show me the documentation for
<bean name="LogBridgeHandler" class="org.jboss.logbridge.LogBridgeHandler"/>
and why it would be needed when building a container based on MC.
Or should I just scan your projects and look for MC beans ? -
6. Re: Tool for documenting MC beans
dmlloyd May 13, 2009 1:14 PM (in response to jesper.pedersen)"jesper.pedersen" wrote:
David, show me the documentation for<bean name="LogBridgeHandler" class="org.jboss.logbridge.LogBridgeHandler"/>
and why it would be needed when building a container based on MC.
Or should I just scan your projects and look for MC beans ?
It's not needed when building a container based on MC. This is, in fact, only needed for JBAS 5.1.x because the old log service is still based on mbeans.
So my point remains.