Yup, I know about the javadocs, the dtd, and the jira issue on documentation. This might be a little different.
Look at Ant or even Maven, the target or goals are documented in a different manner than javadocs. This helps since going from an api description in javadocs or some other manner to the actual xml bean descriptor 'syntax' is hard. Reading a DTD to determine what is allowed is not enjoyable.
Sure editors fill in the xml stuff based on the DTD but this does not help reading and understanding something, only using it.
Right now I use the Reference docs, javadocs, unit tests, and the book to try to understand something. Sometimes the unit tests are the best. Which just adds to the unit tests being a good thing.