Update MF documentation on charge.

johnmay · Nov 28, 2016 · 4803746 · 4803746
1 parent e60c7aa
commit 4803746
Show file tree

Hide file tree

Showing 3 changed files with 21 additions and 26 deletions.
diff --git a/base/data/src/main/java/org/openscience/cdk/formula/MolecularFormula.java b/base/data/src/main/java/org/openscience/cdk/formula/MolecularFormula.java
@@ -62,7 +62,7 @@ public class MolecularFormula implements IMolecularFormula {
     /**
      *  The partial charge of the molecularFormula. The default value is Double.NaN.
      */
-    private Integer                charge           = (Integer) CDKConstants.UNSET;
+    private Integer                charge           = null;
 
     /**
      *  A hashtable for the storage of any kind of properties of this IChemObject.
@@ -150,12 +150,7 @@ public boolean contains(IIsotope isotope) {
     }
 
     /**
-     *  Returns the partial charge of this IMolecularFormula. If the charge
-     *  has not been set the return value is Double.NaN.
-     *
-     * @return the charge of this IMolecularFormula
-     *
-     * @see    #setCharge
+     * {@inheritDoc}
      */
     @Override
     public Integer getCharge() {
@@ -214,11 +209,7 @@ public Iterable<IIsotope> isotopes() {
     }
 
     /**
-     *  Sets the partial charge of this IMolecularFormula.
-     *
-     * @param  charge  The partial charge
-     *
-     * @see    #getCharge
+     * {@inheritDoc}
      */
     @Override
     public void setCharge(Integer charge) {

diff --git a/base/interfaces/src/main/java/org/openscience/cdk/interfaces/IMolecularFormula.java b/base/interfaces/src/main/java/org/openscience/cdk/interfaces/IMolecularFormula.java
@@ -116,7 +116,20 @@ public interface IMolecularFormula extends ICDKObject {
     public void removeAllIsotopes();
 
     /**
-     *  Sets the partial charge of this IMolecularFormula.
+     * Sets the charge of this IMolecularFormula, since there is no atom
+     * associated with the charge the number of a given isotope is not modified.
+     *
+     * <pre>{@code
+     *   // Correct usage
+     *   IMolecularFormula phenolate = MolecularFormulaManipulator.getMolecularFormula("C6H5O", builder)
+     *   mf.setCharge(-1);
+     *   // MF=C6H5O-
+     *
+     *   // Wrong! the H6 is not automatically adjust
+     *   IMolecularFormula phenolate = MolecularFormulaManipulator.getMolecularFormula("C6H6O", builder)
+     *   mf.setCharge(-1);
+     *   // MF=C6H6O- (wrong)
+     * }</pre>
      *
      * @param  charge  The partial charge
      *
@@ -125,8 +138,8 @@ public interface IMolecularFormula extends ICDKObject {
     public void setCharge(Integer charge);
 
     /**
-     *  Returns the partial charge of this IMolecularFormula. If the charge
-     *  has not been set the return value is Double.NaN.
+     * Access the charge of this IMolecularFormula. If the charge
+     * has not been set the return value is null.
      *
      * @return the charge of this IMolecularFormula
      *

diff --git a/base/silent/src/main/java/org/openscience/cdk/silent/MolecularFormula.java b/base/silent/src/main/java/org/openscience/cdk/silent/MolecularFormula.java
@@ -147,12 +147,7 @@ public boolean contains(IIsotope isotope) {
     }
 
     /**
-     *  Returns the partial charge of this IMolecularFormula. If the charge
-     *  has not been set the return value is Double.NaN.
-     *
-     * @return the charge of this IMolecularFormula
-     *
-     * @see    #setCharge
+     * {@inheritDoc}
      */
     @Override
     public Integer getCharge() {
@@ -211,11 +206,7 @@ public Iterable<IIsotope> isotopes() {
     }
 
     /**
-     *  Sets the partial charge of this IMolecularFormula.
-     *
-     * @param  charge  The partial charge
-     *
-     * @see    #getCharge
+     * {@inheritDoc}
      */
     @Override
     public void setCharge(Integer charge) {