Publish Javadoc as HTML

[pdurbin]

Today we discussed how we'd like to write more Javadoc. I feel like @michbarsinai has lead the way and @bencomp expressed interest in more Javadoc in #775. Certainly it would help collaborators get into the code.

It should be pretty easy to generate. mvn javadoc:javadoc is enough to create target/site/apidocs/index.html on my laptop but I'm sure we can put this in our pom.xml so it happens on every build. For now I uploaded the HTML version to http://dvn-vm1.hmdc.harvard.edu/tmp/javadoc/2015-09-14/bb695f3/apidocs/ but we should find it a good home on the web.

[pdurbin]

On a related note, I used to publish a new version of our database schema at https://apitest.dataverse.org/guides/developers/database/schemaspy/relationships.html on every build for the "apitest" server per my update at #775 (comment) but now that apitest tracks production these period builds are not being done and the schemaspy data is never updated. @eaquigley how do you feel about having subdomains of dataverse.org like http://javadoc.dataverse.org or http://schemaspy.dataverse.org ? Or perhaps these could live under a new subdomain as http://dev.dataverse.org/javadoc and http://dev.dataverse.org/schemaspy or something.

[bencomp]

I feel this is really an IQSS internal issue, although it helps all developers to have a stable location. Have you considered guides.dataverse.org? Maybe as part of the API guide or developers' guide?

[pdurbin]

In 661990d I started having phoenix.dataverse.org generate schemaspy reports but I haven't decided which hostname to use. I'm leaning toward http://schemaspy.dataverse.org and plan to have "/latest" so we can version it some day if we want to.

[pdurbin]

In 661990d I started having phoenix.dataverse.org generate schemaspy reports but I haven't decided which hostname to use.

As mentioned at http://irclog.iq.harvard.edu/dataverse/2016-03-22#i_33134 to @bmckinney and @pameyer I decided to go with http://phoenix.dataverse.org/schemaspy/latest/relationships.html as the URL. Again, the schemaspy docs are updated with every build of "phoenix". As of this writing that's typically this job: https://build.hmdc.harvard.edu:8443/job/phoenix.dataverse.org-deploy-develop/

[pameyer]

@pdurbin - at least as of 6783bde, mvn javadoc:javadoc fails with what appear to be problems with to "@todo" in javadoc comments.

[pdurbin]

@pameyer yeah, if you check out https://build.hmdc.harvard.edu:8443/job/phoenix.dataverse.org-javadoc-develop/5/consoleFull for example you'll see all kinds of errors and the job is marked as failed. And yet somehow, some amount of docs are created and uploaded on every build by rsync -av --checksum --delete target/site phoenix.dataverse.org:/var/www/html/site/latest which is a "post" step I have set to "Run regardless of build result". You can find what does get built at http://phoenix.dataverse.org/site/latest/site/apidocs/

At some point we should start a branch and pull request to make it so this Jenkins job completes without error.

[pdurbin]

I just created https://build.hmdc.harvard.edu:8443/job/phoenix.dataverse.org-javadoc-2513-no_doc_lint/ which points to https://github.com/pameyer/dataverse/tree/2513-no_doc_lint by @pameyer and deploys the HTML version of the Javadoc to http://phoenix.dataverse.org/site/2513-no_doc_lint/site/apidocs/

Since @pameyer is actively working on this, I'll put it in Development at https://waffle.io/IQSS/dataverse and assign it to him.

[djbrooke]

per @pameyer , this is ready for code review. Removing his assignment.

[pdurbin]

The command line equivalent of the fix in pull request #3516 seems to be mvn javadoc:javadoc -Dadditionalparam=-Xdoclint:none which I found at http://blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html

The global additionalparam is being used, which seems fine. The blog post suggests that we could add this instead, but I wouldn't bother:

  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-javadoc-plugin</artifactId>
      <configuration>
        <additionalparam>-Xdoclint:none</additionalparam>
      </configuration>
    </plugin>
  </plugins>

If we want to get more granular than "none" some day we can take a look at http://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html to find stuff like javadoc -Xdoclint:html -Xdoclint:syntax -Xdoclint:accessibility

In short, it seems like a good fix! Thanks @pameyer! Passing to QA in https://waffle.io/IQSS/dataverse

[kcondon]

Closing based on info from Phil.

[pdurbin]

Now that pull request #3516 has been merged, we aren't getting errors at https://build.hmdc.harvard.edu:8443/job/phoenix.dataverse.org-javadoc-develop/ . Thanks, @pameyer ! There's still the question of where these docs will live. For now they are at http://phoenix.dataverse.org/site/latest/site/apidocs/

[pdurbin]

@landreev mentioned in retrospective today that we should write more Javadoc and I agree. I just clicked "Build Now" at https://build.hmdc.harvard.edu:8443/job/phoenix.dataverse.org-javadoc-develop/ and here's how our Javadoc looks as of 4e75b2b (4.8.1 plus a few commits):

http://phoenix.dataverse.org/site/latest/site/apidocs/