[tor-bugs] #16873 [metrics-lib]: add javadoc to metrics-lib

[Tor Bug Tracker & Wiki]

#16873: add javadoc to metrics-lib
-------------------------+-----------------------------------
 Reporter:  iwakeh       |          Owner:  karsten
     Type:  enhancement  |         Status:  needs_information
 Priority:  Low          |      Milestone:
Component:  metrics-lib  |        Version:
 Severity:  Normal       |     Resolution:
 Keywords:               |  Actual Points:
Parent ID:  #18746       |         Points:
 Reviewer:               |        Sponsor:
-------------------------+-----------------------------------

Comment (by iwakeh):

 Thanks for the link to Oracle's javadoc style guide!
 I'll add it to the list for discussion about the guide docs.

 A longer comment below.
 Maybe, for release 2.0.0 keep the javadoc comments as they are (here in
 ServerDescriptor)
 and make additions once we have the guide docs in place?
 Javadoc rules should definitely be part of the contributor's guide.

 At the very end of this comment there is a diff with a javadoc ant task
 for metrics-lib.

 == thoughts about comments
 Well, some conventions are not that useful in my opinion.

 It's not that helpful to read something like
 {{{
 #!java
 /**
  * This method returns my foo.
  *
  * @return Foo - the Foo
  */
  public Foo getFoo(){
     return myFoo;
 }

 }}}

 or

 {{{
 #!java
 /**
  * This method returns the bar belonging to foo.
  * @param foo the foo that determines the bar
  * @return the bar for foo
  */
  public Bar retrieveBarOfFoo(Foo foo){
     ...
 }

 }}}

 Such comments just clutter the java file uselessly, b/c the code
 (or the methods' signatures) actually speaks well for itself.
 I prefer reading the code to reading an outdated or
 halfhazardly written comment that communicates nothing or
 even something wrong.

 It is quite a lot of work to keep comments as useful as they are
 in the jdk javadoc, for example.

 From a pragmatic point of view and for a project with a small
 number of developers, I think the javadoc you added to ServerDescriptor
 is currently the best approach.

 This
 {{{
 #!java
 /** Return the SHA-256 descriptor digest, encoded as 43 base64
   * characters without padding characters, that may be used to reference
   * this server descriptor from a network status descriptor. */
  public String getServerDescriptorDigestSha256();
 }}}
 I find easier to read than
 {{{
 #!java
 /** Return the SHA-256 descriptor digest, encoded as 43 base64
  * characters without padding characters, that may be used to reference
  * this server descriptor from a network status descriptor.
  *
  * @return the String containing the SHA-256 digest */
 public String getServerDescriptorDigestSha256();
 }}}

 == simple Javadoc task for metrics-lib
 (actually stolen from metrics-db :-)
 There is no javadoc ant task yet in metrics-lib:

 {{{
 #!diff
 diff --git a/build.xml b/build.xml
 index f7ef7ca..9eb2c0b 100644
 --- a/build.xml
 +++ b/build.xml
 @@ -2,6 +2,7 @@
    <property name="release.version" value="1.1.0-dev" />
    <property name="sources" value="src"/>
    <property name="classes" value="classes"/>
 +  <property name="docs" value="javadoc/"/>
    <property name="tests" value="test"/>
    <property name="libs" value="lib"/>
    <property name="jarfile" value="descriptor-${release.version}.jar" />
 @@ -27,12 +28,14 @@
        <fileset dir="${classes}" defaultexcludes="false" includes="**" />
      </delete>
      <delete file="${jarfile}"/>
 +    <delete file="${docs}"/>
      <delete file="${jarsourcesfile}"/>
      <delete file="${release.tarball}"/>
    </target>

    <target name="init">
      <mkdir dir="${classes}"/>
 +    <mkdir dir="${docs}"/>
    </target>

    <target name="compile"
 @@ -50,6 +53,14 @@
      </javac>
    </target>

 +  <target name="docs">
 +    <mkdir dir="${docs}"/>
 +    <javadoc destdir="${docs}">
 +      <classpath refid="classpath"/>
 +      <fileset dir="${sources}/" includes="**/*.java" />
 +    </javadoc>
 +  </target>
 +
    <target name="test" depends="compile">
      <javac destdir="${classes}"
             srcdir="${tests}"
 }}}

--
Ticket URL: <https://trac.torproject.org/projects/tor/ticket/16873#comment:7>
Tor Bug Tracker & Wiki <https://trac.torproject.org/>
The Tor Project: anonymity online