Tool for documenting MC beans

[jesper.pedersen]

Since a lot of hooking our services together have moved to the -jboss-beans.xml we need a way of documenting those beans, so other projects can get a quicker overview of what's available.

Of course the beans should provide sane defaults for many of the properties, but there are a lot of cases where properties are used directly with a value or gets injected with another bean.

Currently in order to get an overview of what a bean actually does, what it depends on and what properties it exposes one have to look at the class definition.

So what I'm looking for is a tool that can generate documentation for classes that are meant to be exposed as MC beans.

Think a tool that can generate documentation sort of like TLD documentation for web libraries.

Another solution is of course to include all the documentation in the developer guide for each project, but lets not go down that road...

[dmlloyd]

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.

[jason.greene]

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.

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

[dmlloyd]

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

[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 ?

[dmlloyd]

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