JavaDoc Common Usage

readme.md

JavaDoc How-To

I think I finally have HTML references down, e.g.

@see <a href="http://a.b.c">Display Text Here</a>

But I still have to look up links, e.g. {@link JSONObject}.

Inline code reference: {@code JSONObject}

How to do a multi-line code block:

<pre><code>
public int incrementByOne(int i) {
  return i + 1;
}
</code></pre>

References

1. http://stackoverflow.com/questions/5915992/javadoc-writing-links-to-methods
2. http://stackoverflow.com/questions/17496038/javadoc-link-to-method-in-other-class
3. http://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#@see
4. http://stackoverflow.com/questions/541920/multiple-line-code-example-in-javadoc-comment

JavaDocHowTo.java

/**
 * Represents the Microsoft Azure AD service. The methods to which you should
 * pay attention are {@link #executeJSONChunkRequest(JSONObject, String, int)}
 * and {@link #setConfigData(String, int, String, JSONObject)}. These are
 * respectively where data requests from <code>DaaS</code> come and where the
 * service is configured.
 * <p>
 * This is the class referenced by collector templates. E.g.
 * 
 * <pre>
 * {@code
 *  "service-identifier": "AzureIdentityTemplate",
 *  "class": "com.netiq.daas.azureservice.AzureService",
 * }
 * </pre>
 * 
 * @author Garve Hays
 */
public class JavaDocHowTo {
  
  /**
   * @return	a {@link org.codehaus.jettison.json.JSONArray} representing
   * 		a generic map consisting of view parameters
   */
  public void linkWithFullClassPath() {
  	
  }
  
  /**
   * @see <a href="https://gist.github.com/gkhays/example.html">Example</a>
   */
  public void methodWithLinkInDescription() {
    
  }
  
  /**
	 * <b>Note</b>: Subsequent to Java 8 you may use IntSream, e.g.
	 * 
	 * <pre>
	 * {@code 
	 * 	int[] a = { 10, 20, 30, 40, 50 };
	 * 	int sum = IntStream.of(a).sum();}
	 * </pre>
	 * 
	 * However Eclipse complains about the static {@link IntStream#of} syntax
	 * and seems to expect {@link Arrays#stream}. Unless you set the workspace
	 * or project compliance level to 1.8. Apparently Guava has
	 * {@code Ints.toArray} while Apache Commons has
	 * {@code ArrayUtils.toPrimitive}.
	 * 
	 * @see <a
	 *      href="http://stackoverflow.com/questions/4550662/how-do-you-find-the-sum-of-all-the-numbers-in-an-array-in-java">How
	 *      do you find the sum of all the numbers in an array in java?</a>
	 * @see <a
	 *      href="http://stackoverflow.com/questions/25360127/intstream-strange-error">IntStream
	 *      strange error</a>
	 * @see <a
	 *      href="http://stackoverflow.com/questions/960431/how-to-convert-listinteger-to-int-in-java">How
	 *      to convert List<Integer> to int[] in Java?</a>
	 * 
	 * @param count
	 *            the upper bound
	 * @return the sum of all the multiples under the upper bound
	 */
	static int sumOfMultiples8(int count) {
		List<Integer> multiples = new ArrayList<Integer>();
		for (int n = 0; n < count; n++) {
			if (isMultipleOfN(3, n)) {
				multiples.add(n);
			} else if (isMultipleOfN(5, n)) {
				multiples.add(n);
			}
		}
		
		// (1) Convert ArrayList to Integer array.
		Integer[] intArray = multiples.toArray(new Integer[multiples.size()]);
		
		// (2) Get an Integer stream.
		Stream<Integer> intStream = Arrays.stream(intArray);
		
		// (3) Using a delegate, sum the elements of the Integer stream.
		int sum = intStream.mapToInt(b -> b.intValue()).sum();
		System.out.println("Java 8 style: " + sum);
		return sum;
	}
}

http://stackoverflow.com/questions/5915992/javadoc-writing-links-to-methods
http://stackoverflow.com/questions/17496038/javadoc-link-to-method-in-other-class
http://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#@see
http://stackoverflow.com/questions/541920/multiple-line-code-example-in-javadoc-comment