Dev guide: How to write documentation

Documentation and inline comments are obligatory. To make documentation as consistent as possible among all classes, make sure to follow these guidelines.

Javadoc

All classes and methods should be properly documented. The javadoc at the beginning of a class should specifically state:

• First line is a short summary of the class, e.g. "Floyd-Warshall all-pairs shortest path algorithm".
• Next lines/paragraphs define the concept, e.g. "A shortest-path in a graph is ..."
• Next lines/paragraphs describe the class, e.g. a description of what the algorithm does.

In case the class implements an algorithm, the Javadoc must state:

• the runtime complexity of the algorithm.
• the source (academic paper/book) which first described the algorithm.
• the books/papers/websites you used to create this specific implementation.
• identify books/papers/websites which describe approaches to improve the current implementation (E.g. "Future optimizations/extensions of this class could include...") or "A faster method can be found in ..."

Here is a complete example:

/**
 * Tests in polynomial time whether a graph is a <a href="http://mathworld.wolfram.com/BergeGraph.html">Berge Graph</a>.
 * A Berge graph is a graph that contains no odd <a href="http://mathworld.wolfram.com/GraphHole.html">hole</a> or odd
 * <a href="http://mathworld.wolfram.com/GraphAntihole.html">anti-hole</a>. An odd hole or odd antihole in a graph $G(V,E)$
 * is an <a href="https://en.wikipedia.org/wiki/Induced_subgraph">induced subgraph</a> of $G$ that is $C_{2k+1}$ or 
 * $\overline{C}_{2k+1}$ (for some $k \geq 2$), respectively.
 * Berge graphs are <a href="http://mathworld.wolfram.com/PerfectGraph.html">perfect</a>.
 * 
 * <Short description of algorithm>
 * 
 * The implementation of this class is based on:
 * Chudnovsky, M. Cornuéjols, G. Liu, X. Seymour, P. Vušković, K. Recognizing Berge Graphs. Combinatorica 25, 2, 143-186, 2005.
 * The runtime complexity is $O(|V|^9)$.
 * 
 * @author you
 */

Another Partial Example:

...This implementation of Edmond's algorithm has a runtime complexity of $O(m \alpha(m,n))$. Edmonds' original algorithm first appeared in Edmonds, J. Paths, trees, and flowers. Canadian Journal of Mathematics 17, 1965, pp. 449-467. This implementation however follows more closely the description provided in Tarjan, R.E. Data Structures and Network Algorithms. Society for Industrial and Applied Mathematics, 1983, chapter 9. In addition, the following sources were used for the implementation:...

Inline comments

It is important that you document long sequences of code and private functions. This enables other developers to understand your implementation, to extend your code with additional functionality, or to simply find and fix bugs.

Math in Javadoc

Math (functions/equations/...) are incorporated in jgrapht's Javadoc using latex. Mathjax is used to automatically render the equations.

Math is included in javadoc in the same ways as you would write math in latex documents. To write inline math, wrap equations in $ signs. E.g. this $4+3$ is an inline equation. To write larger blocks of math, wrap the equations in brackets: \[ 4+3 \].

For more details on math functionality in latex, see LaTeX math and LaTeX advanced math.

Here is a complete example:

/**
 * Compute the <a href="http://mathworld.wolfram.com/GraphEccentricity.html">eccentricity</a> of
 * each vertex in the graph. The eccentricity of a vertex $u$ is defined as $\max_{v}d(u,v)$,
 * where $d(u,v)$ is the shortest path between vertices $u$ and $v$. If the graph is
 * disconnected, the eccentricity of each vertex is {@link Double#POSITIVE_INFINITY}. The
 * runtime complexity of this method is $O(n^2+L)$, where $L$ is the runtime complexity of the
 * shortest path algorithm provided during construction of this class.
 *
 * @return a map containing the eccentricity of each vertex.
 */

Notes:

• When building Javadoc, it may happen that you get the error: not valid html. This happens for instance when you try to compile the following (valid) Javadoc:
  /** My javadoc \[\begin{align} 4+5 & 6+7 \end{align}\] */
  Although correct, the Javadoc parser doesn't recognize the math block. In this case, the error is thrown because of the & sign. Replacing & by the html encoding & solves the issue.

Example code

Besides code/Javadoc comments, example code and tutorials can also be very helpful to users. Learn more about how to contribute those.