[jboss-user] [Microcontainer] - Re: Tool for documenting MC beans
david.lloyd@jboss.com
do-not-reply at jboss.com
Wed May 13 12:12:09 EDT 2009
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
More information about the jboss-user
mailing list