Here is an example of Javadoc in CVS with ViewVC
There are some advantages to Javadoc being stored in CVS and accessible over viewVC:
- Someone checking out the project can see docs without building (sometimes figuring out config files can be time consuming)
- Javadoc would be versioned, and we would be able to browse any branch, any time
- The history of the documentation with comments would be able to be viewed (as long as we commit the new javadoc when committing the code)
- It would be instantly available (note there is a delay of committing to being viewable on ViewVC of an hour or more), no need to move to a static server
There is a disadvantage that if ViewVC goes away we will have stale links... this is from SteveO:
"we intend to support viewvc or something like it going forward. we don't guarantee that we will keep urls the same if we update to a new piece of software but i do not foresee that anytime soon."
To get Javadoc to work on ViewVC, some massaging needs to happen:
1. The branch will be in the URL, so the branch needs to be known by the build script, so get this from a new property in build.properties
#cvs branch cvs.branch=HEAD
Note: If the code is branched, this property will need to be changed in the new branch... it might be possible to get from a CVS metadata file...
2. The javadoc generation should not commit new files each time it is generated unless something changes. So the timestamp should be removed. (-notimestamp)
<javadoc destdir="doc/api" classpathref="ws.class.path" access="public" additionalparam="-notimestamp" > <packageset dir="src/grouper-ws" defaultexcludes="yes"> <include name="edu/internet2/middleware/grouper/**" /> </packageset> <link href="http://struts.apache.org/1.2.x/api/" /> <link href="http://java.sun.com/j2ee/sdk_1.3/techdocs/api" /> <link href="http://java.sun.com/j2se/1.4.2/docs/api" /> </javadoc>
3. After the javadoc is generated, the links need to be changed so that it is compatible with the URL params in viewvc... (see example in grouper-ws)
<!-- replace .html?edu/internet2/middleware/grouper/webservices/GrouperService.html" with
.html" -->
<!-- take out existing params, these are used by javascript to go to frames gracefully, trash them -->
<replaceregexp flags="g">
<regexp pattern="\.html\?[^" ]*"" />
<substitution expression="\.html"" />
<fileset dir="doc/api" includes="**/*.html" />
</replaceregexp>
<!-- replace relative links, e.g. method links -->
<replaceregexp flags="g">
<regexp pattern="\.html#([^">]*)"" />
<substitution expression="\.html?root=I2MI&view=co&pathrev=${cvs.branch}#\1"" />
<fileset dir="doc/api" includes="**/*.html" />
</replaceregexp>
<!-- replace onLoad="top.loadFrames()" with onLoad="", this javascript messes things up with viewvc params -->
<replace file="doc/api/index.html">
<replacetoken><![CDATA[onLoad="top.loadFrames()"]]></replacetoken>
<replacevalue><![CDATA[onLoad=""]]></replacevalue>
</replace>
<!-- replace for cvs web: .html" with .html?root=I2MI&view=co&pathrev=HEAD" -->
<replace dir="doc/api" value=".html?root=I2MI&view=co&pathrev=${cvs.branch}"">
<include name="**/*.html" />
<replacetoken><![CDATA[.html"]]></replacetoken>
</replace>
<replace dir="doc/api" value=".css?root=I2MI&view=co&pathrev=${cvs.branch}"">
<include name="**/*.html" />
<replacetoken><![CDATA[.css"]]></replacetoken>
</replace>