[Cruisecontrol-devel] [JIRA] Commented: (CC-202) generate configxml.html automatically

[Dan R. (JIRA) <ji...@us...>]

    [ http://jira.public.thoughtworks.org/browse/CC-202?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_18825 ] 

Dan Rollo commented on CC-202:
------------------------------

Hi Seth, and team, 

Nice Work! This fairly large patch went in flawlessly.

I made some minor changes suggested by code inspections, like making a number of the mutator methods (setters) on gendoc 'info' classes (data holders) package visible (instead of protected).
If any of my changes cause you problems, let me know and we'll find a solution.
(Note: If feels like some of these 'info' classes could have many, if not all of their members made final -> eg: be made immutable, but that could be a @todo for the next wave. ;)

While I'm not real jazzed about putting *.html files in the source tree (a la: net.sourceforge.cruisecontrol.config.DefaultPropertiesPlugin.html), I don't have a better solution to offer right now.
Is it expected that most all plugins will have an associated *.html gendoc file? Or is the use of the @DescriptionFile annotation expected to be rare?
We should document a "best practice" regarding this (and of course accompany it with a request for people to help flesh out the documentation via gendoc annotations, towards the end of replacing the static doc with the gendoc. To do that, I want to understand what we expect the end state to be, regarding such class.html files. 

Has any more validation/testing occurred on the jmx gendoc methods? (Not a blocker, but just wondering where they stand).

Committed!

Thanks,
Dan

PS: I also add a 'clean-gendo' target to delete the gendoc.css and config output files (and twiddled with adding the copy-css to init to get targets happy). Seems like we may have some ant target dependency issues in the main build...but that's not really your problem. ;)

> generate configxml.html automatically
> -------------------------------------
>
>                 Key: CC-202
>                 URL: http://jira.public.thoughtworks.org/browse/CC-202
>             Project: CruiseControl
>          Issue Type: Improvement
>          Components: Documentation
>    Affects Versions: 2.2.1
>            Reporter: Jerome Lacoste
>         Assigned To: Dan Rollo
>            Priority: Trivial
>         Attachments: CC-202-part2-v1.diff, configxml.html, configxml.html, configxml.html, configxml.html, Gendoc Design Proposal v2.0.pdf, net.sourceforge.cruisecontrol.ProjectConfig.xml, patch-v2.0.diff, patch-v2.1.diff, patch-v2.2.diff, patch-v2.3.diff, patch-v2.4.diff, patch-v2.5.diff, patch-v2.6.diff, patch-v6-part1.diff, patch-v6-part2.diff, patch_before_cleanup_and_full_conversion.diff, patch_v3.diff, patch_v4.diff, patch_v5.diff, proof-of-concept-diff.log, proof-of-concept-diff.txt, proof-of-concept-diff.txt
>
>
> Several people have expressed their desire of having such feature.
> xdoclet sounds like a good candidate for this problem. If addressed that way, this issue can be broken down in several steps:
> - identify the documentation requirements
> - create a tag specification that would allow to solve these requirements. 
>   We might lose some features as we will perhaps not be able to be as flexible as with the manual documentation
> - write the xdoclet tags that help to generate the intermediate XML
> - create an XSL template that generates the HTML from the intermediate XML
> - move the current configxml.html into tags inside the code
> - update the build/release process to generate the documentation

-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://jira.public.thoughtworks.org/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira