Add API documentation for statistics (#6364)

This PR adds documentation for api::Statistics and api::Stat, as well as further explanations in sphinx.
It also adds a custom css to our sphinx theme that slightly changes how inline code blocks look.

2 files changed, 83 insertions, 40 deletions

diff --git a/src/api/cpp/cvc5.cpp b/src/api/cpp/cvc5.cpp
index 4dbd06ce8..c5472cdfe 100644
--- a/src/api/cpp/cvc5.cpp
+++ b/src/api/cpp/cvc5.cpp
@@ -4147,7 +4147,7 @@ bool Stat::isInt() const
 int64_t Stat::getInt() const
 {
   CVC5_API_TRY_CATCH_BEGIN;
-  CVC5_API_CHECK(isInt()) << "Expected Stat of type int64_t.";
+  CVC5_API_RECOVERABLE_CHECK(isInt()) << "Expected Stat of type int64_t.";
   return std::get<int64_t>(d_data->data);
   CVC5_API_TRY_CATCH_END;
 }
@@ -4158,7 +4158,7 @@ bool Stat::isDouble() const
 double Stat::getDouble() const
 {
   CVC5_API_TRY_CATCH_BEGIN;
-  CVC5_API_CHECK(isDouble()) << "Expected Stat of type double.";
+  CVC5_API_RECOVERABLE_CHECK(isDouble()) << "Expected Stat of type double.";
   return std::get<double>(d_data->data);
   CVC5_API_TRY_CATCH_END;
 }
@@ -4169,7 +4169,7 @@ bool Stat::isString() const
 const std::string& Stat::getString() const
 {
   CVC5_API_TRY_CATCH_BEGIN;
-  CVC5_API_CHECK(isString()) << "Expected Stat of type std::string.";
+  CVC5_API_RECOVERABLE_CHECK(isString()) << "Expected Stat of type std::string.";
   return std::get<std::string>(d_data->data);
   CVC5_API_TRY_CATCH_END;
 }
@@ -4180,14 +4180,14 @@ bool Stat::isHistogram() const
 const Stat::HistogramData& Stat::getHistogram() const
 {
   CVC5_API_TRY_CATCH_BEGIN;
-  CVC5_API_CHECK(isHistogram()) << "Expected Stat of type histogram.";
+  CVC5_API_RECOVERABLE_CHECK(isHistogram()) << "Expected Stat of type histogram.";
   return std::get<HistogramData>(d_data->data);
   CVC5_API_TRY_CATCH_END;
 }
 
-Stat::Stat(bool expert, bool def, StatData&& sd)
+Stat::Stat(bool expert, bool defaulted, StatData&& sd)
     : d_expert(expert),
-      d_default(def),
+      d_default(defaulted),
       d_data(std::make_unique<StatData>(std::move(sd)))
 {
 }
@@ -4250,8 +4250,8 @@ bool Statistics::iterator::operator!=(const Statistics::iterator& rhs) const
 Statistics::iterator::iterator(Statistics::BaseType::const_iterator it,
                                const Statistics::BaseType& base,
                                bool expert,
-                               bool def)
-    : d_it(it), d_base(&base), d_showExpert(expert), d_showDefault(def)
+                               bool defaulted)
+    : d_it(it), d_base(&base), d_showExpert(expert), d_showDefault(defaulted)
 {
   while (!isVisible())
   {
@@ -4270,15 +4270,15 @@ const Stat& Statistics::get(const std::string& name)
 {
   CVC5_API_TRY_CATCH_BEGIN;
   auto it = d_stats.find(name);
-  CVC5_API_CHECK(it != d_stats.end())
+  CVC5_API_RECOVERABLE_CHECK(it != d_stats.end())
       << "No stat with name \"" << name << "\" exists.";
   return it->second;
   CVC5_API_TRY_CATCH_END;
 }
 
-Statistics::iterator Statistics::begin(bool expert, bool def) const
+Statistics::iterator Statistics::begin(bool expert, bool defaulted) const
 {
-  return iterator(d_stats.begin(), d_stats, expert, def);
+  return iterator(d_stats.begin(), d_stats, expert, defaulted);
 }
 Statistics::iterator Statistics::end() const
 {
diff --git a/src/api/cpp/cvc5.h b/src/api/cpp/cvc5.h
index 96e287f84..b3785c10e 100644
--- a/src/api/cpp/cvc5.h
+++ b/src/api/cpp/cvc5.h
@@ -2342,10 +2342,12 @@ struct CVC5_EXPORT RoundingModeHashFunction
 
 /**
  * Represents a snapshot of a single statistic value.
- * A value can be of type int64_t, double, std::string or a histogram
+ * A value can be of type `int64_t`, `double`, `std::string` or a histogram
  * (`std::map<std::string, uint64_t>`).
- * The value type can be queried (using `isInt`, `isString`, etc.) and
- * the stored value can be accessed (using `getInt`, `getString`, etc.).
+ * The value type can be queried (using `isInt()`, `isDouble()`, etc.) and
+ * the stored value can be accessed (using `getInt()`, `getDouble()`, etc.).
+ * It is possible to query whether this statistic is an expert statistic by
+ * `isExpert()` and whether its value is the default value by `isDefault()`.
  */
 class CVC5_EXPORT Stat
 {
@@ -2354,33 +2356,67 @@ class CVC5_EXPORT Stat
  public:
   friend class Statistics;
   friend std::ostream& operator<<(std::ostream& os, const Stat& sv);
+  /** Representation of a histogram: maps names to frequencies. */
   using HistogramData = std::map<std::string, uint64_t>;
-  /** Create from the given value. */
+  /** Can only be obtained from a `Statistics` object. */
   Stat() = delete;
+  /** Copy constructor */
   Stat(const Stat& s);
+  /** Destructor */
   ~Stat();
+  /** Copy assignment */
   Stat& operator=(const Stat& s);
 
-  /** Is this value intended for experts only? */
+  /**
+   * Is this value intended for experts only?
+   * @return Whether this is an expert statistic.
+   */
   bool isExpert() const;
-  /** Does this value hold the default value? */
+  /**
+   * Does this value hold the default value?
+   * @return Whether this is a defaulted statistic.
+   */
   bool isDefault() const;
 
-  /** Is this value an integer? */
+  /**
+   * Is this value an integer?
+   * @return Whether the value is an integer.
+   */
   bool isInt() const;
-  /** Return the integer value */
+  /**
+   * Return the integer value.
+   * @return The integer value.
+   */
   int64_t getInt() const;
-  /** Is this value a double? */
+  /**
+   * Is this value a double?
+   * @return Whether the value is a double.
+   */
   bool isDouble() const;
-  /** Return the double value */
+  /**
+   * Return the double value.
+   * @return The double value.
+   */
   double getDouble() const;
-  /** Is this value an string? */
+  /**
+   * Is this value a string?
+   * @return Whether the value is a string.
+   */
   bool isString() const;
-  /** Return the string value */
+  /**
+   * Return the string value.
+   * @return The string value.
+   */
   const std::string& getString() const;
-  /** Is this value an histogram? */
+  /**
+   * Is this value a histogram?
+   * @return Whether the value is a histogram.
+   */
   bool isHistogram() const;
-  /** Return the histogram value */
+  /**
+   * Return the histogram value.
+   * @return The histogram value.
+   */
   const HistogramData& getHistogram() const;
 
  private:
@@ -2392,6 +2428,9 @@ class CVC5_EXPORT Stat
   std::unique_ptr<StatData> d_data;
 };
 
+/**
+ * Print a `Stat` object to an ``std::ostream``.
+ */
 std::ostream& operator<<(std::ostream& os, const Stat& sv) CVC5_EXPORT;
 
 /**
@@ -2399,25 +2438,23 @@ std::ostream& operator<<(std::ostream& os, const Stat& sv) CVC5_EXPORT;
  * Once obtained, an instance of this class is independent of the `Solver`
  * object: it will not change when the solvers internal statistics do, it
  * will not be invalidated if the solver is destroyed.
- * Statistics are generally categorized as public and expert statistics.
- * Furthermore, statistics may hold the default values and thus be not of
- * interest.
  * Iterating on this class (via `begin()` and `end()`) shows only public
- * statistics that have been set. By passing appropriate flags to `begin()`,
- * statistics that are expert, unchanged, or both, can be included as well.
- * A single statistic value is represented as `Stat`.
+ * statistics that have been changed. By passing appropriate flags to
+ * `begin()`, statistics that are expert, defaulted, or both, can be
+ * included as well. A single statistic value is represented as `Stat`.
  */
 class CVC5_EXPORT Statistics
 {
  public:
-  friend Solver;
+  friend class Solver;
+  /** How the statistics are stored internally. */
   using BaseType = std::map<std::string, Stat>;
 
-  /** Custom iterator to hide expert statistics from regular iteration */
+  /** Custom iterator to hide certain statistics from regular iteration */
   class iterator
   {
    public:
-    friend Statistics;
+    friend class Statistics;
     BaseType::const_reference operator*() const;
     BaseType::const_pointer operator->() const;
     iterator& operator++();
@@ -2431,7 +2468,7 @@ class CVC5_EXPORT Statistics
     iterator(BaseType::const_iterator it,
              const BaseType& base,
              bool expert,
-             bool def);
+             bool defaulted);
     bool isVisible() const;
     BaseType::const_iterator d_it;
     const BaseType* d_base;
@@ -2439,17 +2476,23 @@ class CVC5_EXPORT Statistics
     bool d_showDefault = false;
   };
 
-  /** Retrieve the statistic with the given name. */
+  /**
+   * Retrieve the statistic with the given name.
+   * Asserts that a statistic with the given name actually exists and throws
+   * a `CVC4ApiRecoverableException` if it does not.
+   * @param name Name of the statistic.
+   * @return The statistic with the given name.
+   */
   const Stat& get(const std::string& name);
   /**
    * Begin iteration over the statistics values.
    * By default, only entries that are public (non-expert) and have been set
    * are visible while the others are skipped.
-   * With `expert` set to true, expert statistics are shown as well.
-   * With `def` set to true, defaulted statistics are shown as well.
+   * @param expert If set to true, expert statistics are shown as well.
+   * @param defaulted If set to true, defaulted statistics are shown as well.
    */
-  iterator begin(bool expert = false, bool def = false) const;
-  /** end iteration */
+  iterator begin(bool expert = false, bool defaulted = false) const;
+  /** End iteration */
   iterator end() const;
 
  private: