From 4f66d852b565697d72944d1d41810f957c7bc51a Mon Sep 17 00:00:00 2001
From: Harry Moffat <hkmoffa@sandia.gov>
Date: Sun, 6 Dec 2009 17:56:45 +0000
Subject: [PATCH] Added more expressive comments.

---
 Cantera/src/thermo/State.h | 32 ++++++++++++++++++++++----------
 1 file changed, 22 insertions(+), 10 deletions(-)

diff --git a/Cantera/src/thermo/State.h b/Cantera/src/thermo/State.h
index 21248e8d3..4d403d4aa 100644
--- a/Cantera/src/thermo/State.h
+++ b/Cantera/src/thermo/State.h
@@ -123,14 +123,18 @@ namespace Cantera {
      */
     doublereal moleFraction(const int k) const;
 
-    /**
-     * Set the mole fractions to the specified values, and then 
-     * normalize them so that they sum to 1.0.
+    
+    //! Set the mole fractions to the specified values, and then 
+    //! normalize them so that they sum to 1.0.
+    /*!
      * @param x Array of unnormalized mole fraction values (input). 
-     * Must have a length greater than or equal to the number of
-     * species.
+     *          Must have a length greater than or equal to the number of
+     *          species.
      *
-     * @param x  Input vector of mole fractions.
+     * @param x  Input vector of mole fractions. There is no restriction
+     *           on the sum of the mole fraction vector. Internally,
+     *           the State object will normalize this vector before
+     *           storring its contents.
      *           Length is m_kk.
      */
     virtual void setMoleFractions(const doublereal* const x);
@@ -176,7 +180,10 @@ namespace Cantera {
      * Must have a length greater than or equal to the number of
      * species.
      *
-     * @param y  Input vector of mass fractions.
+     * @param y  Input vector of mass fractions. There is no restriction
+     *           on the sum of the mass fraction vector. Internally,
+     *           the State object will normalize this vector before
+     *           storring its contents.
      *           Length is m_kk.
      */
     virtual void setMassFractions(const doublereal* const y);
@@ -209,9 +216,14 @@ namespace Cantera {
      */
     doublereal concentration(const int k) const;
 
-    /**
-     * Set the concentrations to the specified values within the
-     * phase. 
+    
+    //! Set the concentrations to the specified values within the
+    //! phase. 
+    /*
+     * We set the concentrations here and therefore we set the
+     * overall density of the phase. We hold the temperature constant
+     * during this operation. Therefore, we have possibly changed
+     * the pressure of the phase by calling this routine.
      *
      * @param c The input vector to this routine is in dimensional
      *        units. For volumetric phases c[k] is the