Non optional connector (modelica#3129)

* Describe new annotation for checking number of connections.
* Do not require that conditionally active connectors are connected; reverting modelica#178
Closes modelica#3117
* Apply suggestions from code review
* Removed elided code as suggested, and indicate that something is missing.
Also reduce to one flange-connector.
* Remove 2nd one; turn into separate PR.
Co-authored-by: Henrik Tidefelt <henrikt@wolfram.com>

chapters/annotations.tex

@@ -447,7 +447,8 @@ \section{Simulations}\label{annotations-for-simulations}\label{simulations}
 \end{annotationdefinition}
 
 
-\section{Single Use of Class}\label{annotation-for-single-use-of-class}\label{single-use-of-class}
+\section{Usage Restrictions}\label{usage-restrictions}
+\subsection{Single Use of Class}\label{annotation-for-single-use-of-class}\label{single-use-of-class}
 
 For state machines it is useful to have single instances of local classes.
 This can be done using:
@@ -458,6 +459,35 @@ \section{Single Use of Class}\label{annotation-for-single-use-of-class}\label{si
 The annotation \fmtannotationindex{singleInstance} in a class indicates that there should only be one component instance of the class, and it should be in the same scope as the class is defined.
 The intent is to remove the class when the component is removed and to prevent duplication of the component.
 
+\subsection{Connection Restrictions}\label{connection-restrictions}
+
+A connector component declaration may have the following annotation:
+\begin{lstlisting}[language=modelica]
+annotation(mustBeConnected = "message");
+\end{lstlisting}%
+\annotationindex{mustBeConnected}
+
+It makes it an error if the connector is not connected from the outside (for a conditional connector this check is only active if the connector is enabled).
+For an array of connectors it applies separately to each element.
+
+\begin{nonnormative}
+This annotation is intended for non-causal connectors, see \cref{restrictions-of-connections-and-connectors}.
+It is particularly suited for stream connectors, see \cref{stream-connectors}.
+\end{nonnormative}
+
+\begin{example}
+This can be used for some optional connectors that should be connected when conditionally enabled.
+\begin{lstlisting}[language=modelica]
+partial model PartialWithSupport
+  Flange_b flange;
+  parameter Boolean useSupport;
+  Support support if useSupport
+    annotation(
+      mustBeConnected = "Support connector should be connected if activated.");
+end PartialWithSupport;
+\end{lstlisting}
+The protected components and connections needed to internally handle the support-connector is omitted.
+\end{example}
 
 \section{Graphical Objects}\label{annotations-for-graphical-objects}\label{graphical-objects}
 

chapters/classes.tex

@@ -552,14 +552,8 @@ \subsection{Conditional Component Declaration}\label{conditional-component-decla
 Adding the component and then removing it ensures that the component is valid.
 
 If a connect equation defines the connection of a non-conditional component \lstinline!c1! with a conditional component \lstinline!c2! and \lstinline!c2! is de-activated, then \lstinline!c1! must still be a declared element.
-\end{nonnormative}
-
-If the condition is true for a public connector containing flow
-variables the connector must be connected from the outside.
 
-\begin{nonnormative}
-The reason for this restriction is that the default flow equation is probably incorrect (since it could otherwise
-be an unconditional connector) and the model cannot check that connector is connected.
+There are annotations to handle the case where the connector should be connected when activated, see \cref{annotations-for-the-graphical-user-interface}.
 \end{nonnormative}
 
 \section{Class Declarations}\label{class-declarations}