Merge pull request #895 from stan-dev/algebra-solvers-cleanup

Fix argument order, missing index entries for variadic solvers

Author: bob-carpenter

src/functions-reference/functions_index.qmd

@@ -59,18 +59,26 @@ and ultimately the computational cost of evaluating the gradients.
 
 ### Call to the algebraic solver
 
+<!-- vector; solve_newton; (function algebra_system, vector y_guess, ...); -->
+\index{{\tt \bfseries solve\_newton }!{\tt (function algebra\_system, vector y\_guess, ...): vector}|hyperpage}
 `vector` **`solve_newton`**`(function algebra_system, vector y_guess, ...)`<br>\newline
 Solves the algebraic system, given an initial guess, using Newton's method.
 {{< since 2.31 >}}
 
+<!-- vector; solve_newton_tol; (function algebra_system, vector y_guess, data real scaling_step, data real f_tol, int max_steps, ...); -->
+\index{{\tt \bfseries solve\_newton\_tol }!{\tt (function algebra\_system, vector y\_guess, data real scaling\_step, data real f\_tol, int max\_steps, ...): vector}|hyperpage}
 `vector` **`solve_newton_tol`**`(function algebra_system, vector y_guess, data real scaling_step, data real f_tol, int max_steps, ...)`<br>\newline
 Solves the algebraic system, given an initial guess, using Newton's method with additional control parameters for the solver.
 {{< since 2.31 >}}
 
+<!-- vector; solve_powell; (function algebra_system, vector y_guess, ...); -->
+\index{{\tt \bfseries solve\_powell }!{\tt (function algebra\_system, vector y\_guess, ...): vector}|hyperpage}
 `vector` **`solve_powell`**`(function algebra_system, vector y_guess, ...)`<br>\newline
 Solves the algebraic system, given an initial guess, using Powell's hybrid method.
 {{< since 2.31 >}}
 
+<!-- vector; solve_powell_tol; (function algebra_system, vector y_guess, data real rel_tol, data real f_tol, int max_steps, ...); -->
+\index{{\tt \bfseries solve\powell\_tol }!{\tt (function algebra\_system, vector y\_guess, data real rel\_tol, data real f\_tol, int max\_steps, ...): vector}|hyperpage}
 `vector` **`solve_powell_tol`**`(function algebra_system, vector y_guess, data real rel_tol, data real f_tol, int max_steps, ...)`<br>\newline
 Solves the algebraic system, given an initial guess, using Powell's hybrid method with additional control parameters for the solver.
 {{< since 2.31 >}}

src/functions-reference/higher-order_functions.qmd

@@ -142,17 +142,17 @@ do so, the current Metropolis proposal gets rejected.
 ## Control parameters for the algebraic solver {#algebra-control.section}
 
 The call to the algebraic solver shown previously uses the default control settings. The `_tol` variant of the solver function
-allows three additional parameters, all of which must be supplied.
+allows three additional parameters, all of which must be supplied before the variadic arguments.
 
 ```stan
-y = solve_newton_tol(system, y_guess, theta, x_r, x_i,
-                     scaling_step, f_tol, max_steps);
+y = solve_newton_tol(system, y_guess,  scaling_step, f_tol, max_steps,
+                     theta, x_r, x_i);
 ```
 
 For the Newton solver the three control arguments are scaling step, function tolerance, and maximum number of steps. For the Powell's hybrid method the three control arguments are relative tolerance, function tolerance, and maximum number of steps. If a Newton step is smaller than the scaling step tolerance, the code breaks, assuming the solver is no longer making significant progress. If set to 0, this constraint is ignored. For Powell's hybrid method the relative tolerance is the estimated relative error of the solver and serves to test if a satisfactory solution has been found. After convergence of the either solver, the proposed solution
 is plugged into the algebraic system and its norm is compared to the function tolerance. If the norm is below the function tolerance, the solution is deemed acceptable.  If the solver solver reaches the maximum number of steps, it stops and returns an error message. If one of the criteria is not met, the
 Metropolis proposal gets rejected with a warning message explaining which criterion
-was not satisfied. 
+was not satisfied.
 
 
 The default values for the control arguments are respectively