More missing javadocs - notably the class documentation for AtomSigna…

…ture and MoleculeSignature

src/main/org/openscience/cdk/signature/AtomSignature.java

@@ -33,7 +33,43 @@
 import signature.AbstractVertexSignature;
 
 /**
- * The signature for a molecule rooted at a particular atom.
+ * <p>
+ * The signature {@cdk.cite FAU03, FAU04} for a molecule rooted at a particular
+ * atom.
+ * </p>
+ * 
+ * <p>
+ * A signature is a description of the connectivity of a molecule, in the form
+ * of a tree-like structure called a directed acyclic graph (DAG). This DAG can
+ * be written out as a string, for example ethane:
+ * </p>
+ * 
+ * <pre>
+ *   [C]([C]([H][H][H])[H][H][H])
+ * </pre>
+ * 
+ * <p>
+ * where each atom is represented by an atom symbol in square brackets. The
+ * branching of the tree is indicated by round brackets. When the molecule has a
+ * cycle, the signature string will have numbers after the atom symbol, like:
+ * </p>
+ * 
+ * <pre>
+ * [C]([C]([C,0])[C]([C,0]))
+ * </pre>
+ * 
+ * <p>
+ * these are known as 'colors' and indicate ring closures, in a roughly similar
+ * way to SMILES notation. Note that the colors start from 0 in this
+ * implementation, in contrast to the examples in {@cdk.cite FAU04}.
+ * </p>
+ * 
+ * <p>
+ * Multiple bonds are represented by symbols in front of the opening square
+ * bracket of an atom. Double bonds are '=', triple are '#'. Since there is a
+ * defined direction for the signature tree, only the child node will have the
+ * bond symbol, and the relevant bond is to the parent.
+ * </p>
  * 
  * @cdk.module signature
  * @author maclean
@@ -43,7 +79,7 @@
 public class AtomSignature extends AbstractVertexSignature {
 
     /**
-     * The atom container to make signatures from
+     * The atom container to make signatures from.
      */
     private IAtomContainer molecule;
 

src/main/org/openscience/cdk/signature/MoleculeSignature.java

@@ -37,7 +37,56 @@
 import signature.SymmetryClass;
 
 /**
- * A signature for an entire molecule.
+ * <p>
+ * A molecule signature is a way to produce {@link AtomSignature}s and to get
+ * the canonical {@cdk.cite FAU04} signature string for a molecule. There are
+ * several possible uses for a molecule signature.
+ * </p>
+ * 
+ * <p>
+ * Firstly, a signature with a height greater than the diameter of a molecule
+ * can be used to reconstruct the molecule. In this sense, the signature string
+ * is like a SMILES {@cdk.cite WEI88, WEI89} string. It is more verbose, but it
+ * will work for all molecules.
+ * </p>
+ * 
+ * <p>
+ * Secondly, the set of signatures for a molecule partition the atoms into
+ * equivalence classes (or 'orbits' - see the {@link Orbit} class). This is
+ * similar to partitioning atoms by Morgan number {@cdk.cite MOR65} except that
+ * it works for 3-regular graphs like fullerenes.
+ * </p>
+ * 
+ * <p>
+ * Thirdly, signatures can be calculated at different heights to give
+ * descriptions of the connectivity around atoms. 'Height' is the same as the
+ * idea of a 'sphere' in HOSE codes, and signatures are also path descriptors in
+ * this sense.
+ * </p>
+ * 
+ * So, for example, to get the canonical signature for a molecule:
+ * 
+ * <pre>
+ * IMolecule diamantane = MoleculeFactory.makeBenzene();
+ * MoleculeSignature moleculeSignature = new MoleculeSignature(diamantane);
+ * String canonicalSignature = moleculeSignature.toCanonicalString();
+ * </pre>
+ * 
+ * to get the orbits of this molecule:
+ * 
+ * <pre>
+ * List&lt;Orbit&gt; orbits = moleculeSignature.calculateOrbits();
+ * </pre>
+ * 
+ * and to get the height-2 signature string of just atom 5:
+ * 
+ * <pre>
+ * String hSignatureForAtom5 = moleculeSignature.signatureStringForVertex(5, 2);
+ * </pre>
+ * 
+ * it is also possible to get AtomSignatures using the signatureForVertex method
+ * - which is just a convenience method equivalent to calling the constructor of
+ * an AtomSignature class.
  * 
  * @cdk.module signature
  * @author maclean
@@ -46,6 +95,9 @@
 @TestClass("org.openscience.cdk.signature.MoleculeSignatureTest")
 public class MoleculeSignature extends AbstractGraphSignature {
 
+    /**
+     * The molecule to use when making atom signatures
+     */
     private IAtomContainer molecule;
 
     /**
@@ -141,6 +193,12 @@ public static IAtomContainer fromSignatureString(String signatureString,
         return builder.getAtomContainer();
     }
 
+    /**
+     * Make a canonical signature string of a given height.
+     * 
+     * @param height the maximum height to make signatures
+     * @return the canonical signature string
+     */
     @TestMethod("toCanonicalSignatureStringTest")
     public String toCanonicalSignatureString(int height) {
         String canonicalSignature = null;