Programming for Social Scientists

This page walks you through making your own documentation.

Along with keeping your code clear, providing well documented code is key to working with other programmers. Fortunately with Java there is a very nice documentation system, which converts some of your code comments into docs.

Here's an template of some documented code taken from the simple Wikipedia page on Javadocs and the Oracle Java code comments page. The copyright info at the top is common, but non-standard - this would usually be in a package-level page, but lots of people put it at the top of files, especially if they aren't in packages. You can find out more about package pages, along with information about embedding images and links to the standard docs, at the Oracle Java code comments page. Note that if you can write HTML, you can write using HTML in your comments and this will stay as HTML in the webpages. Note, also, on version numbers this useful scheme (see also Wikipedia).

// package and import information here.

/** * @author Firstname Lastname <address @ example.com> * @version 1.82 24 Dec 2012 (Version number and/or date of class) */ public class Blah {

/** * Description of the variable here. */ private double instanceVariable = 0.0;

/** * Short one line description of method. * * Longer description. If there were any, it would be * here. * * @param variable Description text text text. * @return Description text text text. */ public double methodName (Type parameter) {

System.out.println("Hello World");

// This comment wouldn't come out in the docs. return 10.0;

}

Note that the comments are tabbed across to the same level as the thing they refer to, to keep the code clear. Note also that it is usual to document instance variables, but not variables inside methods.

Here's an example for a class that stores a 2D array of data:

/* * Storage.java 1.0 10 Nov 2011 * * Copyright (c) School of Geography. * University of Leeds, Leeds, West Yorkshire, UK. LS2 9JT * All rights reserved. * * This code is provided under the Academic Academic Free License v. 3.0. * For details, please see the http://www.opensource.org/licenses/AFL-3.0. */

/** * This class stores geographical data. * It contains an accessor method. * @author Dr Andy Evans: http://www.geog.leeds.ac.uk/people/a.evans * @version 1.0 10 Nov 2011 */ public class Storage {

/** * Stores geographical data. */ private double[][] data = new double[300][300];

/** * Returns the current data array. * * The data array is a 300 by 300 array of * landscape or other geographical data. * * @return An array of geographical data. */ double[][] getData () {

// Here's an inline comment. return data;

}

Here's the documentation this little class generates: Docs. Note that the copyright block comment at the top of the documentation doesn't come out in the docs, nor do any inline comments.

Have a look at the docs and compare it to the code above to see where different things come out, then document your code appropriately (ie. all the methods and instance variables). Once you've done this, try writing your own comments for a set of class files you have, go to a command prompt in the directory the class files are in, and type:

javadoc -d docs -private -author -version *.java

You may need to use:

"C:\Program Files\Java\jdk1.8.0\bin\javadoc" -d docs -private -author -version *.java

or equivalent, if you haven't got the PATH to the Java bin set up.

This will create a sub-directory called docs and a set of documentation that includes details of the author, version number, and private elements (which are usually left out). Go to the sub-directory in Windows Explorer and open the file index.html in your web browser to see it.

Once you're happy with your documentation, we're done. If you haven't yet looked at it, work through the tutorial on reading the docs, which will also help you decide what to put in your own doc comments.

Writing Documentation