Merge pull request #439 from stan-dev/deprecation-policy-update

Update deprecation sections to reflect new policy

Author: WardBrian

src/functions-reference/_bookdown.yml

@@ -15,6 +15,7 @@ rmd_files: [
   "compound_arithmetic_and_assignment.Rmd",
   "higher-order_functions.Rmd",
   "deprecated_functions.Rmd",
+  "removed_functions.Rmd",
   "conventions_for_probability_functions.Rmd",
   "discrete_distributions.Rmd",
   "binary_distributions.Rmd",

src/functions-reference/deprecated_functions.Rmd

@@ -1,19 +1,55 @@
 # Deprecated Functions
 
 This appendix lists currently deprecated functionality along with how to
-replace it. These deprecated features are likely to be removed in the future.
+replace it.
 
-```{r results='asis', echo=FALSE}
-if (knitr::is_html_output()) {
-  cat(' * <a href="functions-old-ode-solver.html">integrate_ode_rk45, integrate_ode_adams, integrate_ode_bdf ODE Integrators</a>\n')
-}
-```
+Starting in Stan 2.29, deprecated functions with drop in replacements (such as
+the renaming of `get_lp` or `multiply_log`) will be removed 3 versions later
+e.g., functions deprecated in Stan 2.20 will be removed in Stan 2.23 and placed
+in [Removed Functions]. The Stan compiler can
+[automatically update](https://mc-stan.org/docs/stan-users-guide/stanc-pretty-printing.html)
+these on the behalf of the user.
+
+
+
+## `multiply_log` and `binomial_coefficient_log` functions
+
+*Deprecated*: Currently two non-conforming functions ending in suffix
+  `_log`.
+
+*Replacement*: Replace `multiply_log(...)` with `lmultiply(...)`.
+ Replace `binomial_coefficient_log(...)` with `lchoose(...)`.
+
+*Scheduled Removal*: Stan 2.32
+
+
+## `get_lp()` function
+
+*Deprecated*: The built-in no-argument function `get_lp()` is deprecated.
+
+*Replacement*: Use the no-argument function `target()` instead.
+
+*Scheduled Removal*: Stan 2.32
+
+## `abs(real x)` function
+
+*Deprecated*: Use of the `abs` function with real-valued arguments
+              is deprecated; use functions `fabs` instead.
+
+
+## Integer division with `operator/`
+
+*Deprecated*: Using `/` with two integer arguments is interpreted as integer
+floor division, such that
+
+$$ 1 / 2 = 0 $$
+
+This is deprecated due to its confusion with real-valued division, where
+
+$$ 1.0 / 2.0 = 0.5 $$
+
+*Replacement*: Use the integer division operator `operator%/%` instead.
 
-```{r results='asis', echo=FALSE}
-if (knitr::is_html_output()) {
-  cat(' * <a href="cov_exp_quad.html">cov_exp_quad</a>\n')
-}
-```
 
 ## integrate_ode_rk45, integrate_ode_adams, integrate_ode_bdf ODE Integrators {#functions-old-ode-solver}
 
@@ -166,7 +202,7 @@ with values consisting of solutions at the specified times.
 The sizes must match, and in particular, the following groups are of
 the same size:
 
-  *   state variables passed into the system function,  derivatives
+*   state variables passed into the system function,  derivatives
 returned by the system function, initial state passed  into the
 solver, and rows of the return value of the solver,
 
@@ -198,42 +234,42 @@ $$
 
 `matrix` **`cov_exp_quad`**`(row_vectors x, real alpha, real rho)`<br>\newline
 The covariance matrix with an exponentiated quadratic kernel of x.
-`r since("2.16")`
+`r since("2.16, deprecated since 2.20, scheduled for removal in 2.32")`
 
 <!-- matrix; cov_exp_quad; (vectors x, real alpha, real rho); -->
 \index{{\tt \bfseries cov\_exp\_quad }!{\tt (vectors x, real alpha, real rho): matrix}|hyperpage}
 
 `matrix` **`cov_exp_quad`**`(vectors x, real alpha, real rho)`<br>\newline
 The covariance matrix with an exponentiated quadratic kernel of x.
-`r since("2.16")`
+`r since("2.16, deprecated since 2.20, scheduled for removal in 2.32")`
 
 <!-- matrix; cov_exp_quad; (array[] real x, real alpha, real rho); -->
 \index{{\tt \bfseries cov\_exp\_quad }!{\tt (array[] real x, real alpha, real rho): matrix}|hyperpage}
 
 `matrix` **`cov_exp_quad`**`(array[] real x, real alpha, real rho)`<br>\newline
 The covariance matrix with an exponentiated quadratic kernel of x.
-`r since("2.16")`
+`r since("2.16, deprecated since 2.20, scheduled for removal in 2.32")`
 
 <!-- matrix; cov_exp_quad; (row_vectors x1, row_vectors x2, real alpha, real rho); -->
 \index{{\tt \bfseries cov\_exp\_quad }!{\tt (row\_vectors x1, row\_vectors x2, real alpha, real rho): matrix}|hyperpage}
 
 `matrix` **`cov_exp_quad`**`(row_vectors x1, row_vectors x2, real alpha, real rho)`<br>\newline
 The covariance matrix with an exponentiated quadratic kernel of x1 and
 x2.
-`r since("2.18")`
+`r since("2.18, deprecated since 2.20, scheduled for removal in 2.32")`
 
 <!-- matrix; cov_exp_quad; (vectors x1, vectors x2, real alpha, real rho); -->
 \index{{\tt \bfseries cov\_exp\_quad }!{\tt (vectors x1, vectors x2, real alpha, real rho): matrix}|hyperpage}
 
 `matrix` **`cov_exp_quad`**`(vectors x1, vectors x2, real alpha, real rho)`<br>\newline
 The covariance matrix with an exponentiated quadratic kernel of x1 and
 x2.
-`r since("2.18")`
+`r since("2.18, deprecated since 2.20, scheduled for removal in 2.32")`
 
 <!-- matrix; cov_exp_quad; (array[] real x1, array[] real x2, real alpha, real rho); -->
 \index{{\tt \bfseries cov\_exp\_quad }!{\tt (array[] real x1, array[] real x2, real alpha, real rho): matrix}|hyperpage}
 
 `matrix` **`cov_exp_quad`**`(array[] real x1, array[] real x2, real alpha, real rho)`<br>\newline
 The covariance matrix with an exponentiated quadratic kernel of x1 and
 x2.
-`r since("2.18")`
+`r since("2.18, deprecated since 2.20, scheduled for removal in 2.32")`

src/functions-reference/real-valued_basic_functions.Rmd

@@ -386,8 +386,8 @@ display the log probability accumulator at various stages of execution
 to see where it becomes ill defined.
 
 [^fn_lp]: This function used to be called `get_lp()`, but that   name
-has been deprecated; using it will print a warning.  The   function
-`get_lp()` will be removed in a future release.
+has been deprecated; using it will print a warning.  The function
+`get_lp()` will be removed in Stan 2.32.0.
 
 <!-- real; target; (); -->
 \index{{\tt \bfseries target }!{\tt (): real}|hyperpage}
@@ -402,7 +402,7 @@ Return the current value of the log probability accumulator.
 `real` **`get_lp`**`()`<br>\newline
 Return the current value of the log probability accumulator;
 **deprecated;** - use `target()` instead.
-`r since("2.5")`
+`r since("2.5, scheduled for removal in 2.32.0")`
 
 Both `target` and the deprecated `get_lp` act like other functions
 ending in `_lp`, meaning that they may only may only be used in the
@@ -1275,7 +1275,7 @@ function is written as $\binom{x}{y}$ and pronounced "x choose y."
 This function generalizes to real numbers using the gamma function.
 For $0 \leq y \leq x$, \[ \mathrm{binomial\_coefficient\_log}(x,y) =
 \log\Gamma(x+1) - \log\Gamma(y+1) - \log\Gamma(x-y+1). \]
-`r since("2.0, deprecated since 2.10")`
+`r since("2.0, deprecated since 2.10, scheduled for removal in 2.32")`
 
 <!-- R; binomial_coefficient_log; (T1 x, T2 y); -->
 \index{{\tt \bfseries binomial\_coefficient\_log }!{\tt (T1 x, T2 y): R}|hyperpage}
@@ -1502,7 +1502,7 @@ _**Warning:**_ This function is deprecated and should be replaced with
 \[ \mathrm{multiply\_log}(x,y) = \begin{cases} 0 & \text{if } x = y =
 0 \\ x \log y & \text{if } x, y \neq 0 \\ \text{NaN} &
 \text{otherwise} \end{cases} \]
-`r since("2.0, deprecated in 2.10")`
+`r since("2.0, deprecated since 2.10, scheduled for removal in 2.32")`
 
 <!-- R; multiply_log; (T1 x, T2 y); -->
 \index{{\tt \bfseries multiply\_log }!{\tt (T1 x, T2 y): R}|hyperpage}

src/functions-reference/removed_functions.Rmd

@@ -0,0 +1,6 @@
+# Removed Functions
+
+Functions which once existed in the Stan language and have since been replaced
+or removed will be listed here.
+
+As of the current version of Stan, there are no such functions.

src/reference-manual/deprecations.Rmd

@@ -1,8 +1,16 @@
-# Deprecated Features {#deprecated-features.appendix}
+# Deprecated Features
 
 This appendix lists currently deprecated functionality along with how
-to replace it.  These deprecated features are likely to be removed in
-the next major release.
+to replace it.
+
+Starting with Stan 2.29, minor (syntax-level) deprecations can be removed 3
+versions after release; e.g., syntax deprecated in Stan 2.20 will be removed in
+Stan 2.23 and placed in [Removed Features]. The Stan compiler can
+[automatically update](https://mc-stan.org/docs/stan-users-guide/stanc-pretty-printing.html)
+many of these on the behalf of the user.
+
+Any feature which changes semantic meaning (such as the upgraded ODE solver
+interface) will not be removed until a major version change (e.g., Stan 3.0).
 
 
 ## Assignment with `<-`
@@ -21,6 +29,7 @@ a <- b;
 a = b;
 ```
 
+*Scheduled Removal*: Stan 2.32
 
 ## `increment_log_prob` statement
 
@@ -42,15 +51,18 @@ underlying log density is incremented with each element.
 target += u;
 ```
 
+*Scheduled Removal*: Stan 2.32
 
 ## `get_lp()` function
 
 
-*Deprecated*: The no-argument function `get_lp()` is deprecated.
+*Deprecated*: The built-in no-argument function `get_lp()` is deprecated.
 
 *Replacement*: Use the no-argument function `target()` instead.
 
 
+*Scheduled Removal*: Stan 2.32
+
 ## `_log` density and mass functions
 
 
@@ -83,10 +95,10 @@ with the log probability mass function
 foo_lpmf(y | ...).
 ```
 
+*Scheduled Removal*: Stan 2.32
 
 ## `cdf_log` and `ccdf_log` cumulative distribution functions
 
-
 *Deprecated*: The log cumulative distribution and complementary
 cumulative distribution functions for a distribution `foo` are
 currently written as `foo_cdf_log` and `foo_ccdf_log`.
@@ -95,15 +107,6 @@ currently written as `foo_cdf_log` and `foo_ccdf_log`.
 Replace `foo_ccdf_log(y, ...)` with `foo_lccdf(y | ...)`.
 
 
-## `multiply_log` and `binomial_coefficient_log` functions
-
-*Deprecated*: Currently two non-conforming functions ending in suffix
-  `_log`.
-
-*Replacement*: Replace `multiply_log(...)` with `lmultiply(...)`.
- Replace `binomial_coefficient_log(...)` with `lchoose(...)`.
-
-
 ## User-defined function with `_log` suffix
 
 *Deprecated*: A user-defined function ending in `_log` can
@@ -123,6 +126,11 @@ target += foo_log(y, ...);
 functions or `_lpmf` for mass functions in the user-defined function.
 
 
+*Scheduled Removal*: Stan 2.32
+
+Note: Following Stan 2.32, users can stil define a function ending in `_log`,
+it will just no longer have a special meaning or support the `~` syntax.
+
 ## `lkj_cov` distribution
 
 *Deprecated*:The distribution `lkj_cov` is deprecated.
@@ -155,6 +163,8 @@ block or as a transformed parameter.  An even more efficient transform
 would use Cholesky factors rather than full correlation matrix types.
 
 
+*Scheduled Removal*: Stan 3.0 or later.
+
 ## `if_else` function
 
 *Deprecated*:The function `if_else` is deprecated.  This function
@@ -176,14 +186,10 @@ with
 x = a ? b : c;
 ```
 
-## `abs(real x)` function
-
-*Deprecated*: Use of the `abs` function with real-valued arguments
-              is deprecated; use functions `fabs` instead.
+*Scheduled Removal*: Stan 2.32
 
 ##  Character `#` as comment prefix
 
-
 *Deprecated*: The use of `#` for line-based comments is
   deprecated.  From the first occurrence of `#` onward, the rest
   of the line is ignored.  This happens after includes are resolved
@@ -192,6 +198,7 @@ x = a ? b : c;
 *Replacement*: Use a pair of forward slashes, `//`, for line
   comments.
 
+*Scheduled Removal*: Stan 2.32
 
 ## Brackets array syntax
 
@@ -219,3 +226,29 @@ array[3] vector[7] mu;
 array[15, 12] matrix[7, 2] mu;
 array[2, 3, 4] cholesky_factor_cov[5, 6] mu;
 ```
+
+*Scheduled Removal*: Stan 2.32
+
+
+## New Keywords
+
+*Deprecated*: The following identifiers will become
+[reserved](#reserved-names)
+in the language in the specified version.
+
+*Replacement*: Rename any variables or functions with these names.
+
+| Identifier | Version |
+|------------|---------|
+| array      | 2.32    |
+| lower      | 2.32    |
+| upper      | 2.32    |
+| offset     | 2.32    |
+| multiplier | 2.32    |
+
+
+## Deprecated Functions
+
+Several built-in Stan functions have been deprecated. Consult the
+[functions reference](https://mc-stan.org/docs/functions-reference/deprecated-functions.html)
+for more information.

src/reference-manual/index.Rmd

@@ -26,9 +26,9 @@ for evaluating the results.  This manual applies to all Stan
 interfaces.
 
 There are two additional interface-neutral manuals, the
-[*Stan Functions Reference*]((https://mc-stan.org/docs/functions-reference/index.html)
+[*Stan Functions Reference*](https://mc-stan.org/docs/functions-reference/index.html)
 listing all the built-in functions and their signatures,
-and the [*Stan User's Guide*]((https://mc-stan.org/docs/stan-users-guide/index.html)
+and the [*Stan User's Guide*](https://mc-stan.org/docs/stan-users-guide/index.html)
 providing examples and programming techniques.
 There is also a separate installation and getting started guide for
 each interface.

src/reference-manual/types.Rmd

@@ -75,8 +75,7 @@ and declares `z` to be a $12 \times 8 \times 15$ array of complex numbers.
 
 Prior to 2.26 Stan models used a different syntax.
 The old syntax has been deprecated and is described
-in [the deprecated features
-chapter]{#deprecated-features.appendix}.
+in the [Deprecated Features] chapter.
 
 
 ### Constrained data types {-}
@@ -1345,7 +1344,7 @@ variables; containers of any sizes may be assigned to function
 arguments.  The constrained matrix types `cov_matrix[K]`,
 `corr_matrix[K]`, `cholesky_factor_cov[K]`, and
 `cholesky_factor_corr[K]` are only assignable to matrices of
-dimensions `matrix[K, K]` types. 
+dimensions `matrix[K, K]` types.
 
 +-------------------+----------------------+----------------------------------------------+
 | Function Argument |        Local         |                   Block                      |
@@ -1462,12 +1461,12 @@ dimensions `matrix[K, K]` types.
 <a name="id:constrained-types.figure"></a>
 
 Additional array types follow the same basic template as the final
-example in the table and can contain any of the previous types. 
+example in the table and can contain any of the previous types.
 The unsized version of arrays with more than one dimension is
 specified by using commas, e.g. `array[ , ]` is a 2-D array.
 
 For more on how function arguments and return types are declared,
-consult the [User's Guide chapter on 
+consult the [User's Guide chapter on
 functions](https://mc-stan.org/docs/stan-users-guide/basic-functions-section.html#type-declarations-for-functions).
 
 ## Compound variable declaration and definition
@@ -1585,4 +1584,4 @@ together, so long as the constraint for each variable is the same:
 
 ```stan
 real<lower=0> x, y;
-```
+```