clean up doxygen errors introduced by new metaprograms

[bob-carpenter]

Description

The new metaprograms introduced recently introduced a host of doxygen warnings:

stan/math/rev/fun/multiply.hpp:545: warning: argument 'm1' of command @param is not found in the argument list of stan::math::multiply(const Mat1 &A, const Mat2 &B)

The symbol m1 doesn't even show up in that file. There are also lots of problems with scalars. In total:

$ make doxygen
mkdir -p doc/api
doxygen doxygen/doxygen.cfg
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/prim/fun/acos.hpp:45: warning: argument 'x' from the argument list of stan::math::acos has multiple @param documentation sections
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/prim/fun/asin.hpp:43: warning: argument 'x' from the argument list of stan::math::asin has multiple @param documentation sections
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/prim/fun/atan.hpp:41: warning: argument 'x' from the argument list of stan::math::atan has multiple @param documentation sections
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/prim/fun/ceil.hpp:37: warning: argument 'x' from the argument list of stan::math::ceil has multiple @param documentation sections
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/prim/fun/cos.hpp:40: warning: argument 'x' from the argument list of stan::math::cos has multiple @param documentation sections
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/prim/fun/cosh.hpp:39: warning: argument 'x' from the argument list of stan::math::cosh has multiple @param documentation sections
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/prim/fun/distance.hpp:31: warning: argument 'x1' of command @param is not found in the argument list of stan::math::distance(const T1 &v1, const T2 &v2)
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/prim/fun/distance.hpp:31: warning: argument 'x2' of command @param is not found in the argument list of stan::math::distance(const T1 &v1, const T2 &v2)
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/prim/fun/exp.hpp:43: warning: argument 'x' from the argument list of stan::math::exp has multiple @param documentation sections
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/prim/fun/fabs.hpp:37: warning: argument 'x' from the argument list of stan::math::fabs has multiple @param documentation sections
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/prim/fun/floor.hpp:37: warning: argument 'x' from the argument list of stan::math::floor has multiple @param documentation sections
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/prim/fun/inv_cloglog.hpp:78: warning: argument 'x' from the argument list of stan::math::inv_cloglog has multiple @param documentation sections
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/prim/fun/inv_sqrt.hpp:39: warning: argument 'x' from the argument list of stan::math::inv_sqrt has multiple @param documentation sections
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/prim/fun/inv_square.hpp:22: warning: argument 'x' from the argument list of stan::math::inv_square has multiple @param documentation sections
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/prim/fun/log.hpp:45: warning: argument 'x' from the argument list of stan::math::log has multiple @param documentation sections
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/prim/fun/log10.hpp:38: warning: argument 'x' from the argument list of stan::math::log10 has multiple @param documentation sections
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/fwd/fun/log_softmax.hpp:23: warning: argument 'x' from the argument list of stan::math::log_softmax has multiple @param documentation sections
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/fwd/fun/log_sum_exp.hpp:54: warning: argument 'x' from the argument list of stan::math::log_sum_exp has multiple @param documentation sections
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/prim/fun/logit.hpp:86: warning: argument 'x' from the argument list of stan::math::logit has multiple @param documentation sections
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/prim/fun/mdivide_left_tri.hpp:59: warning: argument 'A' from the argument list of stan::math::mdivide_left_tri has multiple @param documentation sections
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/rev/fun/multiply.hpp:545: warning: argument 'm1' of command @param is not found in the argument list of stan::math::multiply(const Mat1 &A, const Mat2 &B)
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/rev/fun/multiply.hpp:545: warning: argument 'm2' of command @param is not found in the argument list of stan::math::multiply(const Mat1 &A, const Mat2 &B)
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/rev/fun/multiply.hpp:545: warning: argument 'm1' of command @param is not found in the argument list of stan::math::multiply(const Mat1 &A, const Mat2 &B)
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/rev/fun/multiply.hpp:545: warning: argument 'm2' of command @param is not found in the argument list of stan::math::multiply(const Mat1 &A, const Mat2 &B)
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/prim/fun/round.hpp:36: warning: argument 'x' from the argument list of stan::math::round has multiple @param documentation sections
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/prim/fun/sinh.hpp:37: warning: argument 'x' from the argument list of stan::math::sinh has multiple @param documentation sections
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/prim/fun/sqrt.hpp:37: warning: argument 'x' from the argument list of stan::math::sqrt has multiple @param documentation sections
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/prim/fun/square.hpp:51: warning: argument 'x' from the argument list of stan::math::square has multiple @param documentation sections
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/prim/fun/sum.hpp:37: warning: argument 'm' of command @param is not found in the argument list of stan::math::sum(const T &v)
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/prim/fun/tan.hpp:39: warning: argument 'x' from the argument list of stan::math::tan has multiple @param documentation sections
/Users/carp/cmdstan/stan/lib/stan_math/stan/math/prim/fun/tanh.hpp:39: warning: argument 'x' from the argument list of stan::math::tanh has multiple @param documentation sections

Current Version:

v3.1.0

[mcol]

Things are a bit better now:

$ make doxygen
mkdir -p doc/api
doxygen doxygen/doxygen.cfg
/home/mcolombo/works/stan-math-git/stan/math/prim/fun/distance.hpp:33: warning: argument 'x1' of command @param is not found in the argument list of stan::math::distance(const T1 &v1, const T2 &v2)
/home/mcolombo/works/stan-math-git/stan/math/prim/fun/distance.hpp:33: warning: argument 'x2' of command @param is not found in the argument list of stan::math::distance(const T1 &v1, const T2 &v2)
/home/mcolombo/works/stan-math-git/stan/math/rev/fun/multiply.hpp:545: warning: argument 'm1' of command @param is not found in the argument list of stan::math::multiply(const Mat1 &A, const Mat2 &B)
/home/mcolombo/works/stan-math-git/stan/math/rev/fun/multiply.hpp:545: warning: argument 'm2' of command @param is not found in the argument list of stan::math::multiply(const Mat1 &A, const Mat2 &B)
/home/mcolombo/works/stan-math-git/stan/math/rev/fun/multiply.hpp:545: warning: argument 'm1' of command @param is not found in the argument list of stan::math::multiply(const Mat1 &A, const Mat2 &B)
/home/mcolombo/works/stan-math-git/stan/math/rev/fun/multiply.hpp:545: warning: argument 'm2' of command @param is not found in the argument list of stan::math::multiply(const Mat1 &A, const Mat2 &B)
/home/mcolombo/works/stan-math-git/stan/math/prim/fun/sum.hpp:37: warning: argument 'm' of command @param is not found in the argument list of stan::math::sum(const T &v)

[syclik]

Current status:

$ make doxygen
mkdir -p doc/api
doxygen doxygen/doxygen.cfg
/Users/daniel/stan-dev/math/stan/math/prim/meta/as_column_vector_or_scalar.hpp:22: error: argument 'a' from the argument list of stan::math::as_column_vector_or_scalar has muliple @param documentation sections (warning treated as error, aborting now)
make: *** [doxygen] Error 1

[syclik]

Updating my local doxygen version to 1.8.18 gives me a different error. (I was on 1.8.15)

$ make doxygen 
mkdir -p doc/api
doxygen doxygen/doxygen.cfg
/Users/daniel/stan-dev/math/stan/math/opencl/kernel_generator/type_str.hpp:28: error: unbalanced grouping commands (warning treated as error, aborting now)
make: *** [doxygen] Error 1

[SteveBronder]

Thats odd, it should be failing on develop since I switched the flag to fail for warnings

[SteveBronder]

I'm not seeing any errors locally

make doxygen mkdir -p doc/api doxygen doxygen/doxygen.cfg doxygen -v 1.8.13

Can you try running make clean-all then make doxygen? Should we update doxygen on jenkins? I'm guessing newer versions are catching this while older versions let is slide

[syclik]

Yay for differences in versions! (That was sarcastic.) I’ll try that.

On Fri, May 8, 2020 at 12:46 PM Steve Bronder notifications@github.com wrote:

I'm not seeing any errors locally

make doxygen mkdir -p doc/api doxygen doxygen/doxygen.cfg doxygen -v 1.8.13

Can you try running make clean-all then make doxygen? Should we update doxygen on jenkins? I'm guessing newer versions are catching this while older versions let is slide

— You are receiving this because you commented.

Reply to this email directly, view it on GitHub https://github.com/stan-dev/math/issues/1793#issuecomment-625906133, or unsubscribe https://github.com/notifications/unsubscribe-auth/AADH6F7NKBH3GMOCVJ6ETADRQQZO7ANCNFSM4LSAN3KQ .

[SteveBronder]

lol ty, if that fails maybe it's just EOL for the doxygen version on jenkins and we should upgrade