Document multiple declarations

src/reference-manual/types.Rmd

@@ -69,7 +69,7 @@ real values, and declares `m` to be a two-dimensional array of
 size $6 \times 7$ containing values that are $3 \times 3$ matrices.
 
 Prior to 2.26 Stan models used a different syntax, with the array
-dimensions defined after the variable identifier. 
+dimensions defined after the variable identifier.
 Equivalent declarations of `x` and `m` with the pre-2.26 syntax:
 
 ```stan
@@ -351,7 +351,7 @@ model {
 }
 ```
 
-Recall that the centered parameterization is achieved with the code 
+Recall that the centered parameterization is achieved with the code
 
 ```stan
 parameters {
@@ -1249,6 +1249,42 @@ Similarly, `vector[ , ]` is the type of a two-dimensional array of
 vectors.
 
 
+
+## Variable declaration
+
+Variables in Stan are declared by giving a type and a name. For example
+
+```stan
+int N;
+vector[N] y;
+array[5] matrix[3, 4] A;
+```
+
+declares a variable `N` that is an integer, a variable `y` that is
+a vector of length `N` (the previously declared variable), and a 
+variable `A`, which is a length-5 array where each element is a 3 by 4
+matrix. 
+
+There are several different places a variable is declared in Stan. They are
+block variables, like those inside `data`, which can have 
+[constraints](#constrained-data-types) and must include sizes for their types,
+like in the above examples. Local variables, like those defined inside loops
+or local blocks cannot be constrained, but still include sizes. Finally, 
+variables declared as [function parameters](#argument-types-and-qualifiers) 
+are not constrained types and _exclude_ sizes.
+
+```stan
+// valid block variables, but not locals or function parameters
+vector<lower=0>[N] u; 
+
+// valid as a block or local variable, but not a function parameter
+array[3] int is; 
+
+// function parameters exclude sizes and cannot be constrained
+void pretty_print_tri_lower(matrix x) { ... }
+
+```
+
 ## Compound variable declaration and definition
 
 Stan allows assignable variables to be declared and defined in a
@@ -1324,3 +1360,44 @@ Any variable that is in scope and any function that is available in
 the block in which the compound declaration and definition appears may
 be used in the expression on the right-hand side of the compound
 declaration and definition statement.
+
+
+## Declaring multiple variables at once
+
+Stan will interpret multiple comma-separated variable names following a single 
+type as declaring multiple new variables. 
+This is available for all variable declarations in all blocks.
+
+### Types for multiple declarations {-}
+
+The code:
+
+```stan
+real x, y;
+```
+is equivalent to
+
+```stan
+real x;
+real y;
+```
+
+As a result, all declarations on the same line must be of the same type.
+
+### Combining with other features {-}
+
+The ability to declare multiple variables can be combined with assignments
+whenever a declare-define is valid, as documented in
+[the section introducing compound declarations and definitions](#compound-variable-declaration-and-definition)
+:
+
+```stan
+real x = 3, y = 5.6
+```
+
+[Constrained data types](#constrained-data-types) can also be declared 
+together, so long as the constraint for each variable is the same:
+
+```stan
+real<lower=0> x, y;
+```