Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use more overview tables for annotations #3628

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Use more overview tables for annotations #3628

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8923170
Use overview table for graphical user interface annotations
henrikt-ma Dec 16, 2024
36021f2
Rewrite broken reference to preferredView 'view'
henrikt-ma Dec 16, 2024
bf16775
Use overview table for usage restriction annotations
henrikt-ma Dec 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
208 changes: 133 additions & 75 deletions chapters/annotations.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -632,27 +632,42 @@ \section{Simulations}\label{annotations-for-simulations}\label{simulations}


\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.
To this end a class may use the annotation:
\begin{lstlisting}[language=modelica]
/*literal*/ constant Boolean singleInstance;
\end{lstlisting}%
\annotationindex{singleInstance}
The annotations listed below are used to restrict the ways in which classes may be used.
\begin{center}
\begin{tabular}{l|l l}
\hline
\tablehead{Annotation} & \tablehead{Description} & \tablehead{Details}\\
\hline
\hline
{\lstinline!singleInstance!} & Allow at most one instane & \Cref{modelica:singleInstance}\\
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
{\lstinline!singleInstance!} & Allow at most one instane & \Cref{modelica:singleInstance}\\
{\lstinline!singleInstance!} & Allow at most one instance & \Cref{modelica:singleInstance}\\

{\lstinline!mustBeConnected!} & Connector must be connected at least once & \Cref{modelica:mustBeConnected}\\
{\lstinline!mayOnlyConnectOnce!} & Connector must be connected at most once & \Cref{modelica:mayOnlyConnectOnce}\\
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Description should be consistent with the name:

Suggested change
{\lstinline!mayOnlyConnectOnce!} & Connector must be connected at most once & \Cref{modelica:mayOnlyConnectOnce}\\
{\lstinline!mayOnlyConnectOnce!} & Connector may at most be connected once & \Cref{modelica:mayOnlyConnectOnce}\\

\hline
\end{tabular}
\end{center}

\begin{annotationdefinition}[singleInstance]
\begin{synopsis}\begin{lstlisting}
/*literal*/ constant Boolean singleInstance;
\end{lstlisting}\end{synopsis}
\begin{semantics}
Allowed for class annotations.
Only has effect when \lstinline!true!, meaning 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.
\begin{nonnormative}
This is useful for the local classes of state machines.
\end{nonnormative}
\end{semantics}
\end{annotationdefinition}

\subsection{Connection Restrictions}\label{connection-restrictions}

A connector component declaration may have the following annotation:
\begin{lstlisting}[language=modelica]
\begin{annotationdefinition}[mustBeConnected]
\begin{synopsis}\begin{lstlisting}
/*literal*/ constant String mustBeConnected;
\end{lstlisting}%
\annotationindex{mustBeConnected}

If specified it makes it an error if the connector does not appear as an inside connector in any connect-equation (for a conditional connector this check is only active if the connector is enabled).
\end{lstlisting}\end{synopsis}
\begin{semantics}
Allowed for connector component declarations.
If specified, it makes it an error if the connector does not appear as an inside connector in any connect-equation (for a conditional connector this check is only active if the connector is enabled).
The string value must be non-empty and provide the reason why it must be connected.
For an array of connectors it applies separately to each element.

Expand All @@ -674,14 +689,16 @@ \subsection{Connection Restrictions}\label{connection-restrictions}
\end{lstlisting}
The protected components and connections needed to internally handle the support-connector is omitted.
\end{example}
\end{semantics}
\end{annotationdefinition}

A connector component declaration may have the following annotation:
\begin{lstlisting}[language=modelica]
/*literal*/ constant String mayOnlyConnectOnce ;
\end{lstlisting}%
\annotationindex{mayOnlyConnectOnce}

If specified it makes it an error if the connector is connected as an inside connector in a connect-equation and thus appears in a connection set if:
\begin{annotationdefinition}[mayOnlyConnectOnce]
\begin{synopsis}\begin{lstlisting}
/*literal*/ constant String mayOnlyConnectOnce;
\end{lstlisting}\end{synopsis}
\begin{semantics}
Allowed for connector component declarations.
If specified, it makes it an error if the connector is connected as an inside connector in a connect-equation and thus appears in a connection set if:
\begin{itemize}
\item For non-stream connectors the connection set has more than two elements.
\item For stream connectors (see \cref{stream-connectors}), the connection set has more than two elements whose flow variable may be negative (based on evaluation of the \lstinline!min!-attribute).
Expand All @@ -707,6 +724,8 @@ \subsection{Connection Restrictions}\label{connection-restrictions}
end MultiPort;
\end{lstlisting}
\end{example}
\end{semantics}
\end{annotationdefinition}


\section{Graphical Objects}\label{annotations-for-graphical-objects}\label{graphical-objects}
Expand Down Expand Up @@ -1364,64 +1383,91 @@ \subsubsection{Edit Input}\label{edit-input}

\section{Graphical User Interface}\label{annotations-for-the-graphical-user-interface}\label{graphical-user-interface}

This section describes the annotations that are used to define properties of the graphical user interface.
The annotations listed below define properties for use in graphical user interfaces.
\begin{center}
\begin{tabular}{l|l l}
\hline
\tablehead{Annotation} & \tablehead{Description} & \tablehead{Details}\\
\hline
\hline
{\lstinline!preferredView!} & Default view when opening class & \Cref{modelica:preferredView}\\
{\lstinline!DocumentationClass!} & Purpose of class is documentation & \Cref{modelica:DocumentationClass}\\
{\lstinline!defaultComponentName!} & Default name for new components & \Cref{modelica:defaultComponentName}\\
{\lstinline!defaultComponentPrefixes!} & Default type prefixes for new components & \Cref{modelica:defaultComponentPrefixes}\\
{\lstinline!missingInnerMessage!} & Message for unresolved \lstinline!outer! & \Cref{modelica:missingInnerMessage}\\
{\lstinline!absoluteValue!} & Quantity is absolute & \Cref{modelica:absoluteValue}\\
{\lstinline!defaultConnectionStructurallyInconsistent!} & Relax verification of non-simulation class & \Cref{modelica:defaultConnectionStructurallyInconsistent}\\
{\lstinline!obsolete!} & Message when using obsolete class & \Cref{modelica:obsolete}\\
{\lstinline!unassignedMessage!} & Hint for unmatched variable & \Cref{modelica:unassignedMessage}\\
{\lstinline!Dialog!} & Setup for component modifications & \Cref{modelica:Dialog}\\
\hline
\end{tabular}
\end{center}

\begin{lstlisting}[language=modelica]
\begin{annotationdefinition}[preferredView]
\begin{synopsis}\begin{lstlisting}
/*literal*/ constant String preferredView;
\end{lstlisting}

\end{lstlisting}\end{synopsis}
\begin{semantics}
The \fmtannotationindex{preferredView} annotation defines the default view when selecting the class.
The $\mathit{view}$ is a \lstinline!String! literal where \lstinline!"info"! means class documentation (``information''), \lstinline!"diagram"! means diagram view, \lstinline!"icon"! means icon view, and \lstinline!"text"! means Modelica source code (``text'').
The value \lstinline!"info"! means class documentation (``information''), \lstinline!"diagram"! means diagram view, \lstinline!"icon"! means icon view, and \lstinline!"text"! means Modelica source code (``text'').
If not specified the default view is tool-specific.
\end{semantics}
\end{annotationdefinition}

\begin{lstlisting}
\begin{annotationdefinition}[DocumentationClass]
\begin{synopsis}\begin{lstlisting}
/*literal*/ constant Boolean DocumentationClass;
\end{lstlisting}%
\annotationindex{DocumentationClass}

\end{lstlisting}\end{synopsis}
\begin{semantics}
Only allowed as class annotation on any kind of class and only having effect when \lstinline!true!, meaning that this class and all classes within it are treated as having the annotation \lstinline!preferredView = "info"!.
If the annotation \lstinline!preferredView! is explicitly set for a class, it has precedence over a \lstinline!DocumentationClass! annotation.

\begin{nonnormative}
A tool may display such classes in special ways.
For example, the description texts of the classes might be displayed instead of the class names, and if no icon is defined, a special information default icon may be displayed in the package browser.
\end{nonnormative}
\end{semantics}
\end{annotationdefinition}

\begin{lstlisting}[language=modelica]
\begin{annotationdefinition}[defaultComponentName]
\begin{synopsis}\begin{lstlisting}
/*literal*/ constant String defaultComponentName;
\end{lstlisting}%
\annotationindex{defaultComponentName}

When creating a component of the given class, and the annotation is specified it gives the recommended component name.
\end{lstlisting}\end{synopsis}
\begin{semantics}
\lstinline!defaultComponentName! is a class annotation giving the recommended component name to use when creating a component of the class.
If the default name cannot be used (e.g., since it is already in use), another name based on \lstinline!defaultComponentName! shall be derived automatically, except as described under \lstinline!defaultComponentPrefixes!.
It is an error if the string is not a valid identifier.
When automatically deriving a name, any trailing `\lstinline!1!' in the \lstinline!defaultComponentName! shall be disregarded.
If not specified, the names of new components are tool-specific.
\end{semantics}
\end{annotationdefinition}

\begin{lstlisting}[language=modelica]
\begin{annotationdefinition}[defaultComponentPrefixes]
\begin{synopsis}\begin{lstlisting}
/*literal*/ constant String defaultComponentPrefixes;
\end{lstlisting}%
\annotationindex{defaultComponentPrefixes}

When creating a component, it is recommended to generate a declaration of the form
\end{lstlisting}\end{synopsis}
\begin{semantics}
\lstinline!defaultComponentPrefixes! is a class annotation giving a whitespace separated list of recommended type prefixes to include in the \lstinline[language=grammar]!type-prefix! part of a \lstinline[language=grammar]!component-clause1! generated when creating a component of the class:
\begin{lstlisting}[language=grammar]
type-prefix type-specifier component-declaration
\end{lstlisting}

The following prefixes may be included in the string \lstinline!prefixes!: \lstinline!inner!,
\lstinline!outer!, \lstinline!replaceable!, \lstinline!constant!, \lstinline!parameter!, \lstinline!discrete!.
The following prefixes may be included in the \lstinline!defaultComponentPrefixes! string: \lstinline!inner!, \lstinline!outer!, \lstinline!replaceable!, \lstinline!constant!, \lstinline!parameter!, \lstinline!discrete!.
The default is an empty string.

\begin{nonnormative}
In combination with \lstinline!defaultComponentName! it can be used to make it easy for users to create \lstinline!inner! components matching the \lstinline!outer! declarations; see also example below.
If the prefixes contain \lstinline!inner! or \lstinline!outer! and the default name cannot be used (e.g., since it is already in use) it is recommended to give a diagnostic.
In combination with \lstinline!defaultComponentName!, \lstinline!defaultComponentPrefixes! can be used to make it easy for users to create \lstinline!inner! components matching the \lstinline!outer! declarations; see also example below.
If the type prefixes contain \lstinline!inner! or \lstinline!outer! and the default name cannot be used (e.g., since it is already in use) it is recommended to give a diagnostic.
\end{nonnormative}
\end{semantics}
\end{annotationdefinition}

\begin{lstlisting}[language=modelica]
\begin{annotationdefinition}[missingInnerMessage]
\begin{synopsis}\begin{lstlisting}
/*literal*/ constant String missingInnerMessage;
\end{lstlisting}%
\annotationindex{missingInnerMessage}

\end{lstlisting}\end{synopsis}
\begin{semantics}
Only has an effect if specified, and the string must then be non-empty.
When specified and an \lstinline!outer! component of the class does not have a corresponding \lstinline!inner! component, the string message may be used as part of a diagnostic message (together with appropriate context), see \cref{instance-hierarchy-name-lookup-of-inner-declarations}.
The default is a tool-specific diagnostic message.
Expand All @@ -1440,27 +1486,31 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte
inner replaceable World world;
\end{lstlisting}
\end{example}
\end{semantics}
\end{annotationdefinition}

A simple type or component of a simple type may have:
\begin{lstlisting}[language=modelica]
/*literal*/ constant Boolean absoluteValue = true;
\end{lstlisting}%
\annotationindex{absoluteValue}

\begin{annotationdefinition}[absoluteValue]
\begin{synopsis}\begin{lstlisting}
/*literal*/ constant Boolean absoluteValue;
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/*literal*/ constant Boolean absoluteValue;
/*literal*/ constant Boolean absoluteValue = true;

Should keep the default.

\end{lstlisting}\end{synopsis}
\begin{semantics}
Allowed for simple types and components of a simple types.
If \lstinline!false!, then the variable defines a relative quantity, and if \lstinline!true! an absolute quantity.

\begin{nonnormative}
When converting between units (in the user-interface for plotting and entering parameters), the unit offset must be ignored for a variable defined with annotation \lstinline!absoluteValue = false!.
This annotation is used in the Modelica Standard Library, for example in \lstinline!Modelica.Units.SI! for the type definition \lstinline!TemperatureDifference!.
For most types there is no unit offset and the annotation is not needed for them.
\end{nonnormative}
\end{semantics}
\end{annotationdefinition}

A model or block definition may contain:
\begin{lstlisting}[language=modelica]
\begin{annotationdefinition}[defaultConnectionStructurallyInconsistent]
\begin{synopsis}\begin{lstlisting}
/*literal*/ constant Boolean defaultConnectionStructurallyInconsistent;
\end{lstlisting}%
\annotationindex{defaultConnectionStructurallyInconsistent}

\end{lstlisting}\end{synopsis}
\begin{semantics}
Allowed for model and block class definitions.
Only has an effect if \lstinline!true!, when it is stated that a \emph{default connection} will result in a structurally inconsistent model or block\footnote{%
For the precise definition of \emph{structurally inconsistent}, see \textcite{Pantelides1988ConsistentInitialization}.}%
.
Expand All @@ -1473,24 +1523,28 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte
Additionally, when a user defined model is structurally inconsistent, a tool should try to pinpoint in which class the error is present.
This annotation avoids then to show a wrong error message.
\end{nonnormative}
\end{semantics}
\end{annotationdefinition}

A class may have the following annotation:
\begin{lstlisting}[language=modelica]
\begin{annotationdefinition}[obsolete]
\begin{synopsis}\begin{lstlisting}
/*literal*/ constant String obsolete;
\end{lstlisting}%
\annotationindex{obsolete}

\end{lstlisting}\end{synopsis}
\begin{semantics}
Allowed for class annotations.
Only has an effect if specified, and the string must then be non-empty.
It indicates that the class ideally should not be used anymore and gives a message indicating the recommended action.
This annotation is not inherited, the assumption is that if a class uses an obsolete class (as a base class or as the class of one of the components) that shall be updated -- ideally without impacting users of the class.
If that is not possible the current class can have also have an \lstinline!obsolete! annotation.
\end{semantics}
\end{annotationdefinition}

A component declaration may have the following annotation:
\begin{lstlisting}[language=modelica]
\begin{annotationdefinition}[unassignedMessage]
\begin{synopsis}\begin{lstlisting}
/*literal*/ constant String unassignedMessage;
\end{lstlisting}%
\annotationindex{unassignedMessage}

\end{lstlisting}\end{synopsis}
\begin{semantics}
Allowed for component declarations.
Only has an effect if specified, and the string must then be non-empty.
When the variable to which this annotation is attached in the declaration cannot be computed due to the structure of the equations, the string can be used as a diagnostic message.

Expand All @@ -1513,9 +1567,11 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte
end Frame;
\end{lstlisting}
\end{example}
\end{semantics}
\end{annotationdefinition}

A component declaration or a short replaceable class definition may have the following annotation:
\begin{lstlisting}[language=modelica]
\begin{annotationdefinition}[Dialog]
\begin{synopsis}\begin{lstlisting}
record Dialog
/*literal*/ constant String tab = "General";
/*literal*/ constant String group = "";
Expand All @@ -1533,9 +1589,9 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte
/*literal*/ constant String filter = "";
/*literal*/ constant String caption = "";
end Selector;
\end{lstlisting}%
\annotationindex{Dialog}

\end{lstlisting}\end{synopsis}
\begin{semantics}
Allowed for component declarations and short replaceable class definitions.
For a short replaceable class definition only the fields \lstinline!tab!, \lstinline!group!, \lstinline!enable! and \lstinline!groupImage! are allowed.

In the organization of a tool's user interface, the \lstinline!tab! shall correspond to a major divisioning of ``tabs'', and \lstinline!group! correspond to sub-divisioning of ``groups'' within each tab.
Expand Down Expand Up @@ -1599,6 +1655,8 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte
\includegraphics[scale=0.5]{tabparameter}\\
\end{center}
\end{example}
\end{semantics}
\end{annotationdefinition}

\subsection{Connector Sizing}\label{connector-sizing}

Expand Down
2 changes: 1 addition & 1 deletion chapters/classes.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -389,7 +389,7 @@ \subsection{Conditional Component Declaration}\label{conditional-component-decla

If a \lstinline!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.

There are annotations to handle the case where the connector should be connected when activated, see \cref{connection-restrictions}.
There are annotations to handle the case where the connector should be connected when activated, see \cref{modelica:mustBeConnected}.
\end{nonnormative}


Expand Down