Opened 3 years ago

Closed 3 years ago

#21614 closed enhancement (fixed)

JavaDoc should contain the version number

Reported by: iwakeh Owned by: metrics-team
Priority: Medium Milestone:
Component: Metrics Version:
Severity: Normal Keywords:
Cc: Actual Points:
Parent ID: Points:
Reviewer: Sponsor:

Description

(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).

Child Tickets

Change History (5)

comment:1 Changed 3 years ago by karsten

Status: newneeds_review

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" />

comment:2 Changed 3 years ago by iwakeh

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"/>

comment:3 Changed 3 years ago by karsten

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.

comment:4 Changed 3 years ago by iwakeh

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.

comment:5 Changed 3 years ago by karsten

Resolution: fixed
Status: needs_reviewclosed

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

Note: See TracTickets for help on using tickets.