...Basically I mostly agree with you. It's not that good to have user docs in the Java Source, but it's better to have the JavaDocs as a documentation than nothing :) (which is today the case - sometimes at least).
Big +1
And Carsten said he was in a "do mood" today so let's try not to slow him down ;-)
...The first step would be a task that does: FileGenerator.java -> userdocs/generators/file.xml (based on the info in the class)
Sounds good.
And if you could find a way (intermediate document?) to put "hooks" into the generated document, it might be easier later on to merge them with narrative documentation.
For example: @cocoondoc-section parameters @cocoondoc-... (tags describing parameters) @cocoondoc-section sitemap-example @cocoondoc-... (tags describing sitemap example)
Which could translate in the XML generated docs to
<section name="parameters"> ... <section name="sitemap-example">
Then, a narrative XML document which completes this reference doc could use elements like
<include-doc-section name="parameters"/>
to easily merge both things.
...But I think, let's do simple steps :)
Yes, *do* is the key here. Go, Carsten, go!
-Bertrand
