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

[david.lloyd@jboss.com]

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.

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

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