[PPL-devel] [GIT] ppl/ppl(master): Improved documentation for frequency().

[Patricia Hill]

Module: ppl/ppl
Branch: master
Commit: 4c45d375b4eced85f65931946464d71f9041cc29
URL:    http://www.cs.unipr.it/git/gitweb.cgi?p=ppl/ppl.git;a=commit;h=4c45d375b4eced85f65931946464d71f9041cc29

Author: Patricia Hill <p.m.hill at leeds.ac.uk>
Date:   Fri Mar 19 08:53:12 2010 +0000

Improved documentation for frequency().

---

 src/Grid.defs.hh       |   12 +++++++++---
 src/Polyhedron.defs.hh |   15 ++++++++++-----
 2 files changed, 19 insertions(+), 8 deletions(-)

diff --git a/src/Grid.defs.hh b/src/Grid.defs.hh
index 59e840f..32d671b 100644
--- a/src/Grid.defs.hh
+++ b/src/Grid.defs.hh
@@ -863,8 +863,14 @@ public:
 
   /*! \brief
     Returns <CODE>true</CODE> if and only if \p *this is not empty and
-    \p expr is discrete in \p *this, in which case the maximum frequency
-    and the value for \p expr that is closest to zero are computed.
+    \p expr intersects with \p *this and \p *this is discrete on the hyperplane
+    defined by \p expr, in which case the frequency of \p *this
+    and the infimum value for \p expr for a point in \p *this are computed.
+
+    If <CODE>true</CODE> is returned then the frequency of a grid \f$\cP\f$
+    with respect to a linear expression \f$e\f$ is the modulus
+    \f$m\f$ such that all the points of the grid \f$\cP\f$ satisfy
+    the congruence \f$e \%= c \pmod{m}\f$ for some value \f$c\f$.
 
     \param expr
     The linear expression for which the frequency is needed;
@@ -876,7 +882,7 @@ public:
     The denominator of the maximum frequency of \p expr;
 
     \param val_n
-    The numerator of a value of \p expr at a point in the grid
+    The numerator of them value of \p expr at a point in the grid
     that is closest to zero;
 
     \param val_d
diff --git a/src/Polyhedron.defs.hh b/src/Polyhedron.defs.hh
index 52f6bb2..e4c54b2 100644
--- a/src/Polyhedron.defs.hh
+++ b/src/Polyhedron.defs.hh
@@ -765,9 +765,10 @@ public:
 		Generator& g) const;
 
   /*! \brief
-    Returns <CODE>true</CODE> if and only if \p *this is not empty and
-    \p expr is discrete in \p *this, in which case the maximum frequency
-    and the value for \p expr that is closest to zero are computed.
+    Returns <CODE>true</CODE> if and only if \p *this intersects with
+    the hyperplane defined by \p expr at a single point; in which case
+    the frequency of \p *this and the infimum value for \p expr for a
+    point in \p *this are computed.
 
     \param expr
     The linear expression for which the frequency is needed;
@@ -789,9 +790,13 @@ public:
     \exception std::invalid_argument
     Thrown if \p expr and \p *this are dimension-incompatible.
 
-    If \p *this is empty or \p expr can take any real number in \p *this,
-    <CODE>false</CODE> is returned and \p freq_n, \p freq_d,
+    If \p expr has no value in \p *this or can take more than one value
+    in \p *this, <CODE>false</CODE> is returned and \p freq_n, \p freq_d,
     \p val_n and \p val_d are left untouched.
+    If \p expr has a unique value in \p *this, then
+    the frequency of a polyhedron \f$\cP\f$ with respect to a linear expression
+    \f$e\f$ is \f$0\f$ and the value is given by \p val_n and \p val_d.
+
   */
   bool frequency(const Linear_Expression& expr,
                  Coefficient& freq_n, Coefficient& freq_d,