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

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

Seth Pollen commented on CC-202:
--------------------------------

Dan,

About the .HTML files:
We could keep them in a parallel tree to the source tree and hard-code the PluginInfoParser to look for the parallel tree. But that doesn't seem much better to me than putting them directly in with the Java files, and it might make it harder to notice if HTML files are actually used by code annotations. @DescriptionFile is meant to be used for big blocks of HTML that are inconvenient to edit as concatenated Java strings. If I quickly scan the existing config.xml reference, it looks like most plugins could probably be doc'd easily without HTML files.

Where would be the best place to document this "best practice"? We could put it on  http://cruisecontrol.sourceforge.net/main/plugins.html#xmldocumentation  or we could put it in the Javadoc comments for @Description and @DescriptionFile. And we too were hoping that we could engage the whole community in converting the existing doc into annotations.

I do realize that we don't have testcases for CruiseControlControllerJMXAdaptor.getPluginInfo() and CruiseControlControllerJMXAdaptor.getPluginHTML(). I'll work on some automated tests for those and have a patch for you shortly.

On another note, it looks like what GenDoc has done was already sort-of done using the PluginDetail class. Our team won't have time to get to this, but do you think at some point this PluginDetail functionality could be merged into PluginInfo? Should our team submit tickets to JIRA for things like this?

Thanks.
--Seth

> 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

        

------------------------------------------------------------------------------
Nokia and AT&T present the 2010 Calling All Innovators-North America contest
Create new apps & games for the Nokia N8 for consumers in  U.S. and Canada
$10 million total in prizes - $4M cash, 500 devices, nearly $6M in marketing
Develop with Nokia Qt SDK, Web Runtime, or Java and Publish to Ovi Store 
http://p.sf.net/sfu/nokia-dev2dev