Extend choicesAllMatching to records. (modelica#3229)

* Extend choicesAllMatching to records.
Closes modelica#321
* Clarify that choicesAllMatching is valid in just two cases.
And also specify that only recommend to present choices anyway for replaceable.

Co-authored-by: Henrik Tidefelt <henrikt@wolfram.com>
Co-authored-by: Elena Shmoylova <eshmoylova@users.noreply.github.com>

chapters/inheritance.tex

@@ -991,15 +991,22 @@ \subsection{Annotations for Redeclaration and Modification}\label{annotation-cho
 The annotation is not restricted to replaceable elements but can also be applied to non-replaceable elements, enumeration types, and simple variables.
 For a \lstinline!Boolean! variable, a \lstinline!choices! annotation may contain the definition \lstinline!checkBox = true!, meaning to display a checkbox to input the values \lstinline!false! or \lstinline!true! in the graphical user interface.
 
-The annotation \lstinline!choicesAllMatching = true!\annotationindex{choicesAllMatching} on a replaceable element indicates that tools should automatically construct a menu with choices of elements usable for replacing it.
+The annotation \lstinline!choicesAllMatching = true!\annotationindex{choicesAllMatching} on the following kinds of elements indicates that tools should automatically construct a menu with appropriate choices.
+\begin{itemize}
+\item For a replaceable element the included elements should be usable for replacing it.
 Exact criteria for inclusion in such a menu are not defined, but there shall be a a way to at least get a selection of classes, \lstinline!A.B.$\ldots$.X.Z!, that are either directly or indirectly derived by inheritance from the constraining class of the declaration, where \lstinline!A! to \lstinline!X! are non-partial packages, and \lstinline!Z! is non-partial.
+\item For a record variable the included elements shall include matching record constants and calls of matching record constructors (matching classes as for replaceable elements).
+\end{itemize}
+
 This menu can be disabled using annotation \lstinline!choicesAllMatching = false!.
 It is possible to combine the two annotations for one declaration, and tools may avoid generating duplicate menu entries in that case.
 \begin{nonnormative}
-The behavior when \lstinline!choicesAllMatching! is not specified; ideally it should present (at least) the same choices as for \lstinline!choicesAllMatching = true;! but if it takes (too long) time to present the list it is better to have \lstinline!choicesAllMatching = false!.
+When \lstinline!choicesAllMatching! is not specified the following behavior is recommended for replaceable elements.
+A tool could ideally present (at least) the same choices as for \lstinline!choicesAllMatching = true!, but if it takes (too long) time to present the list it might be better to use the \lstinline!choicesAllMatching = false! behavior instead.
 \end{nonnormative}
 
 \begin{example}
+Demonstrating the \lstinline!choices! and  \lstinline!choicesAllMatching = true! annotations applied to replaceable elements.
 \begin{lstlisting}[language=modelica]
 replaceable model MyResistor = Resistor
   annotation(choices(
@@ -1021,8 +1028,29 @@ \subsection{Annotations for Redeclaration and Modification}\label{annotation-cho
   constrainedby Modelica.Media.Interfaces.PartialMedium
   annotation(choicesAllMatching = true);
 \end{lstlisting}
+\end{example}
 
-It can also be applied to nonreplaceable declarations, e.g.\ to describe enumerations.
+\begin{example}
+Demonstrating the \lstinline!choicesAllMatching = true! annotation for parameter records.
+\begin{lstlisting}[language=modelica]
+record Medium
+  parameter SI.Density rho "Density";
+  $\ldots$
+end Medium;
+
+record Air_30degC = Medium(rho = 1.149, $\ldots$);
+constant Medium MyAir = Medium(rho = 1.1, $\ldots$);
+
+model OpenTank
+  parameter Medium medium = Medium() annotation(choicesAllMatching = true);
+end OpenTank;
+\end{lstlisting}
+The choices for \lstinline!medium! shall include \lstinline!Medium()!, \lstinline!Air_30degC()!, and \lstinline!MyAir!.
+If \lstinline!Medium()! is chosen it is necessary to also set its \lstinline!rho!-parameter.
+\end{example}
+
+\begin{example}
+Applying the \lstinline!choices! annotation to nonreplaceable declarations, e.g., to describe enumerations.
 \begin{lstlisting}[language=modelica]
 type KindOfController = Integer(min = 1, max = 3)
   annotation(choices(
@@ -1036,7 +1064,7 @@ \subsection{Annotations for Redeclaration and Modification}\label{annotation-cho
 A a(x = 3 "PID");
 \end{lstlisting}
 
-It can also be applied to \lstinline!Boolean! variables to define a check box.
+The \lstinline!choices! annotation can also be applied to \lstinline!Boolean! variables to define a check box.
 \begin{lstlisting}[language=modelica]
 parameter Boolean useHeatPort = false annotation(choices(checkBox = true));
 \end{lstlisting}