JavaDoc should contain the version number

(This is actually a Metrics/metrics-base ticket, but that component doesn't exist.)

Including the version number would be easiest in the footer (similar to including the year).

added component::metrics owner::metrics-team priority::medium resolution::fixed severity::normal status::closed type::enhancement labels

Or how about we add the version number to the <h1>, as in "DescripTor 1.6.0 API Documentation"? That's something that a few random other JavaDocs do that I just found on the internet. Patch:

diff --git a/build.xml b/build.xml
index fb926c2..1133fe6 100644
--- a/build.xml
+++ b/build.xml
@@ -7,7 +7,7 @@
 <project default="usage" name="descriptor" basedir=".">
 
   <property name="release.version" value="1.6.0-dev" />
-  <property name="javadoc-title" value="DescripTor API Documentation"/>
+  <property name="javadoc-title" value="DescripTor ${release.version} API Documentation"/>
   <property name="javadoc-excludes" value="**/impl/** **/index/**" />
   <property name="implementation-title" value="DescripTor" />
   <property name="name" value="descriptor" />

Trac:
Status: new to needs_review

Main headline is fine location, too. Additional question is if the revision should be put anywhere? Thinking of people rolling their own versions, but just an idea.

Regarding the patch (which would also alter the title and only be in metrics-lib): The version could be appended to the doctitle and be effective for all metrics-base using products, e.g., in base.xml

 <javadoc destdir="${docs}"
             stylesheetfile="${javadocstyle}"
             footer="&amp;copy; ${copyyear} The Tor Project"
-            doctitle="${javadoc-title}"
+            doctitle="${javadoc-title} ${release.version}"
             overview="${basedir}/${resources}/overview.html"
             use="true"
             windowtitle="${javadoc-title}">
      <classpath refid="classpath"/>

How about we add the revision to -dev versions only, but not to released versions? So, "DescripTor 1.6.0 API Documentation" and "DescripTor 1.6.0-dev 5b1db5d API Documentation"?

Speaking of, your patch appends the version as in: "DescripTor API Documentation 1.6.0-dev", but the version seems a bit out of place there at the end. How about we put together the doctitle in base.xml by using "${implementation-title} ${release-version} API Documentation", possibly with the option to override it? Plus the revision.

Yes, your suggestions about having the version in the middle and only add the git-revision in case of dev versions makes sense.

Please review this patch.

Example:

DescripTor 1.6.0 API Documentation
DescripTor 1.6.0-dev.abcdefg API Documentation

I would want to wait with adding the override options until we really saw a use case.

Looks good! Merged and pushed to master. Closing. Thanks!

Trac:
Resolution: N/A to fixed
Status: needs_review to closed

closed