[Springframework-developer] Documentation in XML bean definition files: Volunteer wanted

[Rod J. <rod...@in...>]

All,

As I believe someone brought up on the forums, we should allow users to add
optional documentation in Spring XML files. This could be as simple as a
change to the DTD, but there are a few issues around how we do it.

It should be possible to attach descriptive text to any bean element, such
as bean, property, constructor-arg, in particular. Also to the document as a
whole.

However, we need to decide on the tradeoff between verbosity and power. E.g.
we could have this:

<bean id="foo" class="whatever" description="This is the application's
magical foo service">
    <property name="delay" description="Milliseconds to delay before
starting another pass">...

This is concise, but attributes are not suited to lengthy text, and some
characters are problematic. So we could promote the description to element
level like this:

<bean id="foo" class="whatever">
    <description>This is the application's magical foo service</description>
    <property name="delay">
        <description>Milliseconds to delay before starting another
pass</description>
        <value>...
    </property>

Now I think this makes sense for the <bean> element. But I don't think it
makes sense for properties. I hate verbose XML formats like anything from
Sun, where they'll never use an attribute where an element would do.

So options include:
- description element for bean and description attribute for finer-grained
elements
- all element can support a description attribute or element a la Ant. I'm
not sure how elegant this is but it would be optimally expressive.
- different names for attribute and element: attribute is shortInfo perhaps
and description element can be longer. Thus it would be rare, but legal, to
add a description element to a property.

We also need to allow a top-level description element for the beans element,
as the first thing.

Of course, all descriptions would be optional, so it wouldn't break existing
applications or add work for those developers who don't care about adding
descriptions.

Another decision is whether to expose bean-level descriptions
programmatically via the BeanDefinition. This may be useful, although I
think it's lower priority than getting the DTD right. Any thoughts on this?
Practical situations in which it would be useful?



Just having descriptions in the XML could be useful, but it would be
particularly good to use that information in XSLT to generate nicely
formated "SpringDoc". This could start off fairly simply, just showing bean
name, description, class, hyperlinked dependencies etc. However, there are
many potential refinements:

- Generating something showing the relationship to related bean factories,
the other factories probably supplied in the tool arguments
- HTML that allows information about a particular bean to be expanded or
collapsed.
- Hyperlinks to the Javadoc for the relevant class if its location is
supplied
- Recognition and possibly "collapsing" of common idioms. E.g. it could
display that "foo" is a bean of type "com.myco.Foo" and that it's an AOP
proxy with the following interceptors.

I will change the DTD based on what we decide and possibly implement any
support for it in the BeanDefinitions, but we need a volunteer to tackle the
XSLT stuff. Hopefully an XSLT wizard with time to take this on will step
forward!

Regards,
Rod

PS Please reply to the dev list. I've cross posted this as I thought that a
user, rather than existing developer, might have the XSLT skills and
willingness to work on this...