Document template parameters in /prim

RELEASE-NOTES.txt

@@ -434,7 +434,7 @@ Bug Fixes
 --------------------------------------------------
 * beta_rng no longer returns NaN
 * fixed memory issue with cholesky_decompose in reverse-mode (#415)
-* no more mulitple definitions when including Stan headers in
+* no more multiple definitions when including Stan headers in
   multiple source files (#394)
 * fixed broken _MSC_VER conditionals and remove math.h includes (#370)
 

runChecks.py

@@ -57,7 +57,7 @@ def check_non_unique_test_names():
             for y in duplicates[x]:
                 duplicates_error_msg += "\t" + y + "\n"
         errors.append(
-            "Tests or test fixtures with non-unqiue names found in test/unit:\n\n" +
+            "Tests or test fixtures with non-unique names found in test/unit:\n\n" +
             duplicates_error_msg
         )
     return errors

stan/math.hpp

@@ -109,17 +109,17 @@
  *
  * In general, these methods allow Stan to have more generic types so that the
  * library can forward along Eigen expression and have better move semantics.
- * For instance, the below code will accept any arbitrary eigen expression
+ * For instance, the code below will accept any arbitrary Eigen expression
  * that, if it's an rvalue, can be forwarded to another function.
  *
  *~~~~~{.cpp}
- *  template <typename Mat1, typename Mat2,
+ * template <typename Mat1, typename Mat2,
  * require_all_eigen_vt<is_arithmetic, Mat1, Mat2>...>
  * inline auto a_func(Mat1&& m1, Mat2&& m2) {
  *   check_nan(m1);
  *   check_nan(m2);
  *   // If m1 and/or m2 is an rvalue it will be moved over to this function
- *  // instead of copied to an lvalue
+ *   // instead of copied to an lvalue
  *   auto B = another_func(std::forward<Mat1>(m1), std::forward<Mat2>(m2)); //
  *(3) return B;
  *~~~~~
@@ -141,7 +141,7 @@
  * certain conditions while @c _st methods check that the objects @c scalar_type
  * fulfills certain conditions. @c value_type and @c scalar_type differ in that
  * @c value_type is the first level of a container while @c scalar_type
- * recursivly goes through containers of containers till it comes to a simple
+ * recursively goes through containers of containers till it comes to a simple
  * type.
  */
 

stan/math/mix/functor/partial_derivative.hpp

@@ -10,7 +10,7 @@ namespace stan {
 namespace math {
 
 /**
- * Return the partial derivative of the specified multiivariate
+ * Return the partial derivative of the specified multivariate
  * function at the specified argument.
  *
  * @tparam T Argument type

stan/math/opencl/cholesky_decompose.hpp

@@ -22,20 +22,20 @@ namespace opencl {
 /** \ingroup opencl
  * Performs an in-place computation of the lower-triangular Cholesky factor
  * (i.e., matrix square root) of the specified square, symmetric matrix. The
- * return value \f$L\f$ will be a lower-traingular matrix such that the original
+ * return value \f$L\f$ will be a lower-triangular matrix such that the original
  * matrix \f$A\f$ is given by <p>\f$A = L \times L^T\f$. The Cholesky
  * decomposition is computed using an OpenCL kernel. This algorithm is
  * recursive. The matrix is subset into a matrix of size <code>A.rows() /
  * 4</code>, and if the submatrix size is less than 50 or <code>min_block</code>
- * then the cholesky decomposition on the OpenCL device is computed using that
+ * then the Cholesky decomposition on the OpenCL device is computed using that
  * submatrix. If the submatrix is greater than 50 or <code>min_block</code> then
  * <code>cholesky_decompose</code> is run again on a submatrix with size equal
- * to <code>submat.rows() / 4</code>. Once the Cholesky Decomposition is
- * computed, the full matrix cholesky is created by propogating the cholesky
+ * to <code>submat.rows() / 4</code>. Once the Cholesky decomposition is
+ * computed, the full matrix Cholesky is created by propagating the Cholesky
  * forward as given in the reference report below.
  *
  * For a full guide to how this works
- * see the Cholesy decompostion chapter in the  reference report
+ * see the Cholesky decomposition chapter in the reference report
  * <a href="https://goo.gl/6kWkJ5"> here</a>.
  * @throw std::domain_error if m is not
  *  positive definite (if m has more than 0 elements)

stan/math/opencl/err/check_opencl.hpp

@@ -14,7 +14,7 @@ namespace math {
 
 /** \ingroup opencl
  * Throws the domain error with specifying the OpenCL error that
- * occured. It outputs the OpenCL errors that are specified
+ * occurred. It outputs the OpenCL errors that are specified
  * in OpenCL 2.0. If no matching error number is found,
  * it throws the error with the number.
  * @param function the name of the function where the error occurred

stan/math/opencl/kernels/matrix_multiply.hpp

@@ -49,7 +49,7 @@ static const std::string matrix_multiply_kernel_code = STRINGIFY(
       for (int w = 0; w < WORK_PER_THREAD; w++) {
         acc[w] = 0.0;
       }
-      // the number of tiles for each scalar product in the matrix mulitply
+      // the number of tiles for each scalar product in the matrix multiply
       const int num_tiles = (K + THREAD_BLOCK_SIZE - 1) / THREAD_BLOCK_SIZE;
       // in case of splitting the matrix multiply we need
       // use split_offset_tiles the threads assigned part

stan/math/opencl/opencl_context.hpp

@@ -136,7 +136,7 @@ class opencl_context_base {
   }
 
  protected:
-  cl::Context context_;  // Manages the the device, queue, platform, memory,etc.
+  cl::Context context_;  // Manages the the device, queue, platform, memory, etc
   cl::CommandQueue command_queue_;       // job queue for device, one per device
   std::vector<cl::Platform> platforms_;  // Vector of available platforms
   cl::Platform platform_;                // The platform for compiling kernels

stan/math/opencl/prim/cholesky_decompose.hpp

@@ -15,7 +15,7 @@ namespace math {
 /**
  * Returns the lower-triangular Cholesky factor (i.e., matrix
  * square root) of the specified square, symmetric matrix on the OpenCL device.
- * The return value \f$L\f$ will be a lower-traingular matrix such that the
+ * The return value \f$L\f$ will be a lower-triangular matrix such that the
  * original matrix \f$A\f$ is given by <p>\f$A = L \times L^T\f$.
  * @param A Input square matrix
  * @return Square root of matrix.

stan/math/prim/err/check_cholesky_factor.hpp

@@ -20,7 +20,7 @@ namespace math {
  * @param function Function name (for error messages)
  * @param name Variable name (for error messages)
  * @param y Matrix to test
- * @throw <code>std::domain_error</code> if y is not a valid Choleksy
+ * @throw <code>std::domain_error</code> if y is not a valid Cholesky
  *   factor, if number of rows is less than the number of columns,
  *   if there are 0 columns, or if any element in matrix is NaN
  */

stan/math/prim/err/check_cholesky_factor_corr.hpp

@@ -16,14 +16,14 @@ namespace math {
  * correlation matrix.
  * A Cholesky factor is a lower triangular matrix whose diagonal
  * elements are all positive.  Note that Cholesky factors need not
- * be square, but requires at least as many rows M as columns N
+ * be square, but require at least as many rows M as columns N
  * (i.e., M >= N).
  * Tolerance is specified by <code>math::CONSTRAINT_TOLERANCE</code>.
  * @tparam T_y Type of elements of Cholesky factor
  * @param function Function name (for error messages)
  * @param name Variable name (for error messages)
  * @param y Matrix to test
- * @throw <code>std::domain_error</code> if y is not a valid Choleksy
+ * @throw <code>std::domain_error</code> if y is not a valid Cholesky
  *   factor, if number of rows is less than the number of columns,
  *   if there are 0 columns, or if any element in matrix is NaN
  */

stan/math/prim/err/check_consistent_sizes.hpp

@@ -32,7 +32,7 @@ inline void check_consistent_sizes(const char* function, const char* name1,
 }
 
 /**
- * Check if the dimension of x1, x2, and x3 areconsistent.
+ * Check if the dimension of x1, x2, and x3 are consistent.
  * Consistent size is defined as having the same size if vector-like or
  * being a scalar.
  * @tparam T1 Type of x1
@@ -61,7 +61,7 @@ inline void check_consistent_sizes(const char* function, const char* name1,
 }
 
 /**
- * Check if the dimension of x1, x2, x3, and x4are consistent.
+ * Check if the dimension of x1, x2, x3, and x4 are consistent.
  * Consistent size is defined as having the same size if
  * vector-like or being a scalar.
  * @tparam T1 Type of x1

stan/math/prim/err/check_nonnegative.hpp

@@ -13,7 +13,7 @@ namespace internal {
 template <typename T_y, bool is_vec>
 struct nonnegative {
   static void check(const char* function, const char* name, const T_y& y) {
-    // have to use not is_unsigned. is_signed will be false
+    // have to use not is_unsigned. is_signed will be false for
     // floating point types that have no unsigned versions.
     if (!std::is_unsigned<T_y>::value && !(y >= 0)) {
       throw_domain_error(function, name, y, "is ", ", but must be >= 0!");

stan/math/prim/err/check_simplex.hpp

@@ -16,7 +16,7 @@ namespace math {
  * Check if the specified vector is simplex.
  * To be a simplex, all values must be greater than or equal to 0
  * and the values must sum to 1.
- * A valid simplex is one where the sum of hte elements is equal
+ * A valid simplex is one where the sum of the elements is equal
  * to 1.  This function tests that the sum is within the tolerance
  * specified by <code>CONSTRAINT_TOLERANCE</code>. This function
  * only accepts Eigen vectors, statically typed vectors, not

stan/math/prim/err/constraint_tolerance.hpp

@@ -6,7 +6,7 @@ namespace stan {
 namespace math {
 
 /**
- * The tolerance for checking arithmetic bounds In rank and in
+ * The tolerance for checking arithmetic bounds in rank and in
  * simplexes.  The default value is <code>1E-8</code>.
  */
 const double CONSTRAINT_TOLERANCE = 1E-8;

stan/math/prim/err/invalid_argument.hpp

@@ -35,7 +35,7 @@ inline void invalid_argument(const char* function, const char* name, const T& y,
  * Throw an invalid_argument exception with a consistently formatted message.
  * This is an abstraction for all Stan functions to use when throwing
  * invalid argument. This will allow us to change the behavior for all
- * functions at once. (We've already changed behavior mulitple times up
+ * functions at once. (We've already changed behavior multiple times up
  * to Stan v2.5.0.)
  * The message is: "<function>: <name> <msg1><y>"
  * @tparam T Type of variable

stan/math/prim/err/invalid_argument_vec.hpp

@@ -13,7 +13,7 @@ namespace math {
  * Throw an invalid argument exception with a consistently formatted message.
  * This is an abstraction for all Stan functions to use when throwing
  * invalid arguments. This will allow us to change the behavior for all
- * functions at once. (We've already changed behavior mulitple times up
+ * functions at once. (We've already changed behavior multiple times up
  * to Stan v2.5.0.)
  * The message is:
  * "<function>: <name>[<i+error_index>] <msg1><y>"
@@ -42,7 +42,7 @@ inline void invalid_argument_vec(const char* function, const char* name,
  * Throw an invalid argument exception with a consistently formatted message.
  * This is an abstraction for all Stan functions to use when throwing
  * invalid arguments. This will allow us to change the behavior for all
- * functions at once. (We've already changed behavior mulitple times up
+ * functions at once. (We've already changed behavior multiple times up
  * to Stan v2.5.0.)
  * The message is:
  * "<function>: <name>[<i+error_index>] <msg1><y>"

stan/math/prim/err/is_cholesky_factor.hpp

@@ -11,17 +11,17 @@ namespace stan {
 namespace math {
 
 /**
- * Return <code>true</code> if y is a valid Choleksy factor, if
+ * Return <code>true</code> if y is a valid Cholesky factor, if
  * number of rows is not less than the number of columns, if there
  * are no 0 columns, and no element in matrix is <code>NaN</code>.
  * A Cholesky factor is a lower triangular matrix whose diagonal
  * elements are all positive.  Note that Cholesky factors need not
- * be square, but requires at least as many rows M as columns N
+ * be square, but require at least as many rows M as columns N
  * (i.e., M &gt;= N).
  * @tparam T_y Type of elements of Cholesky factor, requires class method
  *   <code>.rows()</code>, <code>.cols()</code>, and <code>.diagonal()</code>
  * @param y Matrix to test
- * @return <code>true</code> if y is a valid Choleksy factor, if
+ * @return <code>true</code> if y is a valid Cholesky factor, if
  *   number of rows is not less than the number of columns,
  *   if there are no 0 columns, and no element in matrix is <code>NaN</code>
  */

stan/math/prim/err/is_matching_size.hpp

@@ -10,7 +10,7 @@ namespace math {
 /**
  * Return <code>true</code> if two structures are the same size.
  * This is a top-level sizing function for <code>std::vector</code>
- * where a 2x3 vector returns 2,and a total sizing function for
+ * where a 2x3 vector returns 2, and a total sizing function for
  * <code>Eigen::Matrix</code> where a 2x3 matrix will return 6.
  * @tparam T_y1 Type of the first variable, requires class method
  *    <code>.size()</code>

stan/math/prim/fun/accumulator.hpp

@@ -14,7 +14,7 @@ namespace math {
  * Class to accumulate values and eventually return their sum.  If
  * no values are ever added, the return value is 0.
  *
- * This class is useful for speeding up auto-diff of long sums
+ * This class is useful for speeding up autodiff of long sums
  * because it uses the <code>sum()</code> operation (either from
  * <code>stan::math</code> or one defined by argument-dependent lookup.
  *
@@ -88,7 +88,7 @@ class accumulator {
   /**
    * Recursively add each entry in the specified standard vector
    * to the buffer.  This will allow vectors of primitives,
-   * auto-diff variables to be added; if the vector entries
+   * autodiff variables to be added; if the vector entries
    * are collections, their elements are recursively added.
    *
    * @tparam S Type of value to recursively add.

stan/math/prim/fun/array_builder.hpp

@@ -10,7 +10,7 @@ namespace math {
 
 /**
  * Structure for building up arrays in an expression (rather than
- * in statements) using an argumentchaining add() method and
+ * in statements) using an argument-chaining add() method and
  * a getter method array() to return the result.
  * Array elements are held in std::vector of type T.
  *

stan/math/prim/fun/asin.hpp

@@ -37,6 +37,7 @@ inline auto asin(const T& x) {
 
 /**
  * Version of asin() that accepts Eigen Matrix or matrix expressions.
+ *
  * @tparam Derived derived type of x
  * @param x Matrix or matrix expression
  * @return Arcsine of each variable in the container, in radians.

stan/math/prim/fun/assign.hpp

@@ -56,8 +56,8 @@ inline void assign(T_lhs& x, const T_rhs& y) {
  * compatible.  The shapes are specified in the row and column
  * template parameters.
  *
- * @tparam T_lhs Type of left-hand side matrix elements.
- * @tparam T_rhs Type of right-hand side matrix elements.
+ * @tparam T_lhs type of elements in the left-hand side matrix
+ * @tparam T_rhs type of elements in the right-hand side matrix
  * @tparam R1 number of rows in the left-hand side matrix or Eigen::Dynamic
  * @tparam C1 number of columns in the left-hand side matrix or Eigen::Dynamic
  * @tparam R2 number of rows in the right-hand side matrix or Eigen::Dynamic
@@ -94,10 +94,10 @@ inline void assign(Eigen::Matrix<T_lhs, R1, C1>& x,
  * <code>Eigen::Matrix</code> types and whose shapes match.  The
  * shapes are specified in the row and column template parameters.
  *
- * @tparam T_lhs Type of left-hand side matrix elements.
- * @tparam T_rhs Type of right-hand side matrix elements.
- * @tparam R number of rows or Eigen::Dynamic
- * @tparam C number of columns or Eigen::Dynamic
+ * @tparam T_lhs type of elements in the left-hand side matrix
+ * @tparam T_rhs type of elements in the right-hand side matrix
+ * @tparam R number of rows, can be Eigen::Dynamic
+ * @tparam C number of columns, can be Eigen::Dynamic
  *
  * @param x Left-hand side matrix.
  * @param y Right-hand side matrix.
@@ -127,10 +127,10 @@ inline void assign(Eigen::Matrix<T_lhs, R, C>& x,
  * used, which still holds onto a reference to the contained
  * matrix and thus still updates the appropriate values.
  *
- * @tparam T_lhs Type of matrix block elements.
- * @tparam T Type of right-hand side matrix elements.
- * @tparam R number of rows or Eigen::Dynamic
- * @tparam C number of columns or Eigen::Dynamic
+ * @tparam T_lhs type of matrix block elements
+ * @tparam T type of elements in the right-hand side matrix
+ * @tparam R number of rows, can be Eigen::Dynamic
+ * @tparam C number of columns, can be Eigen::Dynamic
  *
  * @param x Left-hand side block view of matrix.
  * @param y Right-hand side matrix.
@@ -162,8 +162,8 @@ inline void assign(Eigen::Block<T_lhs> x, const Eigen::Matrix<T, R, C>& y) {
  * assigned to a <code>std::vector&lt;double&gt;</code> using this
  * function.
  *
- * @tparam T_lhs Type of left-hand side vector elements.
- * @tparam T_rhs Type of right-hand side vector elements.
+ * @tparam T_lhs type of elements in the left-hand side vector
+ * @tparam T_rhs type of elements in the right-hand side vector
  * @param x Left-hand side vector.
  * @param y Right-hand side vector.
  * @throw std::invalid_argument if sizes do not match.

stan/math/prim/fun/atan.hpp

@@ -37,6 +37,7 @@ inline typename apply_scalar_unary<atan_fun, T>::return_t atan(const T& x) {
 
 /**
  * Version of atan() that accepts Eigen Matrix or matrix expressions.
+ *
  * @tparam Derived derived type of x
  * @param x Matrix or matrix expression
  * @return Elementwise atan of members of container.

stan/math/prim/fun/autocorrelation.hpp

@@ -10,6 +10,7 @@
 namespace stan {
 namespace math {
 namespace internal {
+
 /**
  * Find the optimal next size for the FFT so that
  * a minimum number of zeros are padded.

stan/math/prim/fun/autocovariance.hpp

@@ -55,7 +55,9 @@ void autocovariance(const std::vector<T>& y, std::vector<T>& acov,
  *     Eigen::FFT<double> fft;
  * </pre>
  *
- * @tparam T Scalar type.
+ * @tparam T scalar type
+ * @tparam DerivedA type of the first matrix
+ * @tparam DerivedB type of the second matrix
  * @param y Input sequence.
  * @param acov Autocovariance.
  * @param fft FFT engine instance.
@@ -106,7 +108,9 @@ void autocovariance(const std::vector<T>& y, std::vector<T>& acov) {
  * <p>This method is just a light wrapper around the three-argument
  * autocovariance function
  *
- * @tparam T Scalar type.
+ * @tparam T scalar type
+ * @tparam DerivedA type of the first matrix
+ * @tparam DerivedB type of the second matrix
  * @param y Input sequence.
  * @param acov Autocovariances.
  */

stan/math/prim/fun/beta.hpp

@@ -41,8 +41,8 @@ namespace math {
    \end{cases}
    \f]
  *
- * @tparam T1 Type of first value.
- * @tparam T2 Type of second value.
+ * @tparam T1 type of first value
+ * @tparam T2 type of second value
  * @param a First value
  * @param b Second value
  * @return Beta function applied to the two values.

stan/math/prim/fun/binomial_coefficient_log.hpp

@@ -8,6 +8,7 @@
 
 namespace stan {
 namespace math {
+
 /**
  * Return the log of the binomial coefficient for the specified
  * arguments.
@@ -54,6 +55,8 @@ namespace math {
    \end{cases}
    \f]
  *
+ * @tparam T_N type of the first argument
+ * @tparam T_n type of the second argument
  * @param N total number of objects.
  * @param n number of objects chosen.
  * @return log (N choose n).