Merge pull request #1181 from bstatcomp/feature/issue-1122-add-comments-to-metaprograms

syclik · web-flow · commit cb204e0bf073 · 2019-03-29T00:01:58.000-04:00
Issue #1122: Add comments to the metaprograms
diff --git a/stan/math/fwd/scal/meta/ad_promotable.hpp b/stan/math/fwd/scal/meta/ad_promotable.hpp
@@ -8,7 +8,18 @@ namespace math {
 
 template <typename T>
 struct fvar;
-
+/**
+ * Template traits metaprogram to determine if a variable
+ * of one template type is promotable to the base type of
+ * a second fvar template type.
+ *
+ * <p>It will declare an enum <code>value</code> equal to
+ * <code>true</code> if the variable type is promotable to
+ * the base type of the fvar template type,
+ * <code>false</code> otherwise.
+ *
+ * @tparam T promoted type
+ */
 template <typename V, typename T>
 struct ad_promotable<V, fvar<T> > {
   enum { value = ad_promotable<V, T>::value };
diff --git a/stan/math/fwd/scal/meta/is_fvar.hpp b/stan/math/fwd/scal/meta/is_fvar.hpp
@@ -5,7 +5,10 @@
 #include <stan/math/prim/scal/meta/is_fvar.hpp>
 
 namespace stan {
-
+/**
+ * Defines a public enum named value and sets it to true(1)
+ * when instantiated with the stan::math::fvar type.
+ */
 template <typename T>
 struct is_fvar<stan::math::fvar<T> > {
   enum { value = true };
diff --git a/stan/math/prim/arr/meta/contains_std_vector.hpp b/stan/math/prim/arr/meta/contains_std_vector.hpp
@@ -6,7 +6,10 @@
 #include <vector>
 
 namespace stan {
-
+/**
+ * Extends std::true_type when instantiated with at least 1 template
+ * parameter of type std::vector<T>.
+ */
 template <typename T, typename... Ts>
 struct contains_std_vector<std::vector<T>, Ts...> : std::true_type {};
 
diff --git a/stan/math/prim/arr/meta/get.hpp b/stan/math/prim/arr/meta/get.hpp
@@ -5,7 +5,13 @@
 #include <vector>
 
 namespace stan {
-
+/**
+ * Returns the n-th element of the provided std::vector.
+ *
+ * @param x input vector
+ * @param n index of the element to return
+ * @return n-th element of the input vector
+ */
 template <typename T>
 inline T get(const std::vector<T>& x, size_t n) {
   return x[n];
diff --git a/stan/math/prim/arr/meta/is_constant_struct.hpp b/stan/math/prim/arr/meta/is_constant_struct.hpp
@@ -6,7 +6,12 @@
 #include <vector>
 
 namespace stan {
-
+/**
+ * Defines a public enum named value and sets it to true(1)
+ * if the type of the elements in the provided std::vector
+ * is a constant struct, false(0) otherwise.
+ * @tparam type of the elements in the std::vector
+ */
 template <typename T>
 struct is_constant_struct<std::vector<T> > {
   enum { value = is_constant_struct<T>::value };
diff --git a/stan/math/prim/arr/meta/length.hpp b/stan/math/prim/arr/meta/length.hpp
@@ -5,7 +5,13 @@
 #include <vector>
 
 namespace stan {
-
+/**
+ * Returns the length of the provided std::vector.
+ *
+ * @param x input vector
+ * @tparam T type of the elements in the vector
+ * @return the length of the input vector
+ */
 template <typename T>
 size_t length(const std::vector<T>& x) {
   return x.size();
diff --git a/stan/math/prim/mat/meta/is_constant_struct.hpp b/stan/math/prim/mat/meta/is_constant_struct.hpp
@@ -6,12 +6,25 @@
 #include <stan/math/prim/scal/meta/is_constant.hpp>
 
 namespace stan {
-
+/**
+ * Defines a public enum named value and sets it to true(1)
+ * if the type of the elements in the provided Eigen matrix
+ * is a constant struct, false(0) otherwise.
+ * @tparam type of the elements in the Eigen matrix
+ * @tparam R number of rows in the provided matrix
+ * @tparam C number of columns in the provided matrix
+ */
 template <typename T, int R, int C>
 struct is_constant_struct<Eigen::Matrix<T, R, C> > {
   enum { value = is_constant_struct<T>::value };
 };
 
+/**
+ * Defines a public enum named value and sets it to true(1)
+ * if the type of the elements in the provided Eigen Block
+ * is a constant struct, false(0) otherwise.
+ * @tparam type of the elements in the Eigen Block
+ */
 template <typename T>
 struct is_constant_struct<Eigen::Block<T> > {
   enum { value = is_constant_struct<T>::value };
diff --git a/stan/math/prim/mat/meta/length.hpp b/stan/math/prim/mat/meta/length.hpp
@@ -5,6 +5,15 @@
 
 namespace stan {
 
+/**
+ * Returns the size of the provided Eigen matrix.
+ *
+ * @param m a const Eigen matrix
+ * @tparam T type of matrix.
+ * @tparam R number of rows in the input matrix.
+ * @tparam C number of columns in the input matrix.
+ * @return the size of the input matrix
+ */
 template <typename T, int R, int C>
 size_t length(const Eigen::Matrix<T, R, C>& m) {
   return m.size();
diff --git a/stan/math/prim/mat/meta/scalar_type.hpp b/stan/math/prim/mat/meta/scalar_type.hpp
@@ -5,27 +5,64 @@
 #include <stan/math/prim/arr/meta/scalar_type.hpp>
 
 namespace stan {
-
+/**
+ * Template metaprogram defining the base scalar type of
+ * values stored in an Eigen matrix.
+ *
+ * @tparam T type of matrix.
+ * @tparam R number of rows for matrix.
+ * @tparam C number of columns for matrix.
+ */
 template <typename T, int R, int C>
 struct scalar_type<Eigen::Matrix<T, R, C> > {
   typedef typename scalar_type<T>::type type;
 };
 
+/**
+ * Template metaprogram defining the base scalar type of
+ * values stored in a const Eigen matrix.
+ *
+ * @tparam T type of matrix.
+ * @tparam R number of rows for matrix.
+ * @tparam C number of columns for matrix.
+ */
 template <typename T, int R, int C>
 struct scalar_type<const Eigen::Matrix<T, R, C> > {
   typedef typename scalar_type<T>::type type;
 };
 
+/**
+ * Template metaprogram defining the base scalar type of
+ * values stored in a referenced  Eigen matrix.
+ *
+ * @tparam T type of matrix.
+ * @tparam R number of rows for matrix.
+ * @tparam C number of columns for matrix.
+ */
 template <typename T, int R, int C>
 struct scalar_type<Eigen::Matrix<T, R, C>&> {
   typedef typename scalar_type<T>::type type;
 };
 
+/**
+ * Template metaprogram defining the base scalar type of
+ * values stored in a referenced const Eigen matrix.
+ *
+ * @tparam T type of matrix.
+ * @tparam R number of rows for matrix.
+ * @tparam C number of columns for matrix.
+ */
 template <typename T, int R, int C>
 struct scalar_type<const Eigen::Matrix<T, R, C>&> {
   typedef typename scalar_type<T>::type type;
 };
 
+/**
+ * Template metaprogram defining the base scalar type of
+ * values stored in an Eigen Block.
+ *
+ * @tparam T type of block.
+ */
 template <typename T>
 struct scalar_type<Eigen::Block<T> > {
   typedef typename scalar_type<T>::type type;
diff --git a/stan/math/prim/scal/meta/contains_fvar.hpp b/stan/math/prim/scal/meta/contains_fvar.hpp
@@ -8,9 +8,10 @@
 namespace stan {
 
 /**
- * Defines a public enum named value which is defined to be true (1)
- * if any of the template parameters includes a fvar as their base scalar and
- * false (0) otherwise.
+ * Extends std::true_type when instantiated with at least 1
+ * template parameter that is a fvar. Extends std::false_type
+ * otherwise.
+ * @tparam T Types to test
  */
 template <typename... T>
 using contains_fvar
diff --git a/stan/math/prim/scal/meta/contains_nonconstant_struct.hpp b/stan/math/prim/scal/meta/contains_nonconstant_struct.hpp
@@ -7,9 +7,10 @@
 namespace stan {
 
 /**
- * Metaprogram to determine if any of the
- * provided types have a base scalar
- * type that cannot be assigned to type double.
+ * Extends std::true_type when instantiated with at least 1
+ * template parameter that is a nonconstant struct.
+ * Extends std::false_type otherwise.
+ * @tparam T Types to test
  */
 template <typename... T>
 using contains_nonconstant_struct
diff --git a/stan/math/prim/scal/meta/contains_std_vector.hpp b/stan/math/prim/scal/meta/contains_std_vector.hpp
@@ -5,6 +5,11 @@
 #include <type_traits>
 
 namespace stan {
+/**
+ * Extends std::false_type as a std::vector type
+ * cannot be a scalar primitive type.
+ * @tparam Ts Types to test
+ */
 template <typename... Ts>
 struct contains_std_vector : std::false_type {};
 }  // namespace stan
diff --git a/stan/math/prim/scal/meta/contains_vector.hpp b/stan/math/prim/scal/meta/contains_vector.hpp
@@ -8,6 +8,7 @@ namespace stan {
 /**
  * Metaprogram to determine if any of the
  * provided types is a std::vector.
+ * @tparam T Types to test
  */
 template <typename... T>
 using contains_vector = math::disjunction<is_vector<T>...>;
diff --git a/stan/math/prim/scal/meta/is_constant_struct.hpp b/stan/math/prim/scal/meta/is_constant_struct.hpp
@@ -8,6 +8,7 @@ namespace stan {
 /**
  * Metaprogram to determine if a type has a base scalar
  * type that can be assigned to type double.
+ * @tparam T Types to test
  */
 template <typename T>
 struct is_constant_struct {
diff --git a/stan/math/prim/scal/meta/is_fvar.hpp b/stan/math/prim/scal/meta/is_fvar.hpp
@@ -2,7 +2,10 @@
 #define STAN_MATH_PRIM_SCAL_META_IS_FVAR_HPP
 
 namespace stan {
-
+/**
+ * Defines a public enum named value which is defined to be false
+ * as the primitive scalar types cannot be a stan::math::fvar type.
+ */
 template <typename T>
 struct is_fvar {
   enum { value = false };
diff --git a/stan/math/prim/scal/meta/is_var.hpp b/stan/math/prim/scal/meta/is_var.hpp
@@ -2,7 +2,10 @@
 #define STAN_MATH_PRIM_SCAL_META_IS_VAR_HPP
 
 namespace stan {
-
+/**
+ * Defines a public enum named value which is defined to be false
+ * as the primitive scalar types cannot be a stan::math::var type.
+ */
 template <typename T>
 struct is_var {
   enum { value = false };
diff --git a/stan/math/prim/scal/meta/length.hpp b/stan/math/prim/scal/meta/length.hpp
@@ -4,7 +4,10 @@
 #include <cstdlib>
 
 namespace stan {
-
+/**
+ * Returns the length of primitive scalar types
+ * that are always of length 1.
+ */
 template <typename T>
 size_t length(const T& /*x*/) {
   return 1U;
diff --git a/stan/math/prim/scal/meta/size_of.hpp b/stan/math/prim/scal/meta/size_of.hpp
@@ -16,6 +16,13 @@ struct size_of_helper<T, true> {
   static size_t size_of(const T& x) { return x.size(); }
 };
 
+/**
+ * Returns the size of the provided vector or
+ * the constant 1 if the input argument is not a vector.
+ * @param x value for which to obtain the size of
+ * @tparam the type of the input value
+ * @return the size of x or 1 if not a vector
+ */
 template <typename T>
 size_t size_of(const T& x) {
   return size_of_helper<T, is_vector<T>::value>::size_of(x);
diff --git a/stan/math/rev/scal/meta/ad_promotable.hpp b/stan/math/rev/scal/meta/ad_promotable.hpp
@@ -6,12 +6,23 @@
 
 namespace stan {
 namespace math {
-
+/**
+ * Template traits metaprogram to determine if a variable of one
+ * template type is promotable to var.
+ *
+ * <p>It will declare an enum <code>value</code> equal to
+ * <code>true</code> if the type is promotable to double,
+ * <code>false</code> otherwise.
+ *
+ * @tparam T promoted type
+ */
 template <typename T>
 struct ad_promotable<T, var> {
   enum { value = ad_promotable<T, double>::value };
 };
-
+/**
+ * A var type is promotable to itself.
+ */
 template <>
 struct ad_promotable<var, var> {
   enum { value = true };
diff --git a/stan/math/rev/scal/meta/is_var.hpp b/stan/math/rev/scal/meta/is_var.hpp
@@ -5,7 +5,10 @@
 #include <stan/math/rev/core.hpp>
 
 namespace stan {
-
+/**
+ * Defines a public enum named value and sets it to true(1)
+ * when instantiated with the stan::math::var type.
+ */
 template <>
 struct is_var<stan::math::var> {
   enum { value = true };
