Skip to content

More consistently describe where an annotation is allowed #3927

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

Open
henrikt-ma wants to merge 2 commits into
base: master
Choose a base branch
from
Open

More consistently describe where an annotation is allowed #3927

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
436da50
More consistently describe where an annotation is allowed
henrikt-ma Jul 7, 2026
4d05e5d
Fix hyphenation of "white-space"
henrikt-ma Jul 7, 2026
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
28 changes: 21 additions & 7 deletions chapters/annotations.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -678,7 +678,6 @@ \section{Simulations}\label{annotations-for-simulations}\label{simulations}
\end{center}

\begin{annotationdefinition}[experiment]

\begin{synopsis}
\begin{lstlisting}[language=modelica]
record experiment
Expand All @@ -690,6 +689,7 @@ \section{Simulations}\label{annotations-for-simulations}\label{simulations}
\end{lstlisting}
\end{synopsis}
\begin{semantics}
Allowed for model and block class annotations.
The \lstinline!experiment! annotation defines the start time (\lstinline!StartTime!) in {[}s{]}, the stop time (\lstinline!StopTime!) in {[}s{]}, the suitable time resolution for the result grid (\lstinline!Interval!) in {[}s{]}, and the relative integration tolerance (\lstinline!Tolerance!) for simulation experiments to be carried out with the model or block at hand.
When \lstinline!Interval! or \lstinline!Tolerance! is not provided, the tool is responsible for applying appropriate defaults.

Expand All @@ -708,6 +708,8 @@ \section{Simulations}\label{annotations-for-simulations}\label{simulations}
/*literal*/ constant Boolean HideResult;
\end{lstlisting}\end{synopsis}
\begin{semantics}
Allowed for component declarations.

\lstinline!HideResult = true! defines that the model developer proposes to not show the simulation results of the corresponding component.

\lstinline!HideResult = false! defines that the developer proposes to show the corresponding component.
Expand All @@ -729,6 +731,7 @@ \section{Simulations}\label{annotations-for-simulations}\label{simulations}
end TestCase;
\end{lstlisting}\end{synopsis}
\begin{semantics}
Allowed for model and block class annotations.
If \lstinline!shouldPass! is \lstinline!false! it indicates that the translation or the simulation of the model should fail.
If a tools checks a package where classes have \lstinline!shouldPass = false! they should not generate errors, and checking may even be skipped.
On the other hand, models with \lstinline!shouldPass = false! may be useful for creation of negative tests in tool-specific ways.
Expand Down Expand Up @@ -1660,6 +1663,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte
/*literal*/ constant String preferredView;
\end{lstlisting}\end{synopsis}
\begin{semantics}
Allowed for class annotations.
The \lstinline{preferredView} annotation defines the default view when selecting the class.
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.
Expand All @@ -1671,7 +1675,8 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte
/*literal*/ constant Boolean 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"!.
Allowed for class annotations.
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}
Expand All @@ -1686,7 +1691,8 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte
/*literal*/ constant String defaultComponentName;
\end{lstlisting}\end{synopsis}
\begin{semantics}
The class annotation \lstinline!defaultComponentName! gives the recommended component name to use when creating a component of the class.
Allowed for class annotations.
Specifies 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.
Expand All @@ -1699,7 +1705,8 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte
/*literal*/ constant String defaultComponentPrefixes;
\end{lstlisting}\end{synopsis}
\begin{semantics}
The class annotation \lstinline!defaultComponentPrefixes! gives a whitespace separated list of recommended type prefixes to include in the \productionref{type-prefix} part of a \productionref{component-clause1} generated when creating a component of the class.
Allowed for class annotations.
Specifies a white-space separated list of recommended type prefixes to include in the \productionref{type-prefix} part of a \productionref{component-clause1} generated when creating a component of the class.

@HansOlsson HansOlsson Jul 8, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Suggested change
Specifies a white-space separated list of recommended type prefixes to include in the \productionref{type-prefix} part of a \productionref{component-clause1} generated when creating a component of the class.
Specifies a whitespace separated list of recommended type prefixes to include in the \productionref{type-prefix} part of a \productionref{component-clause1} generated when creating a component of the class.

So, no change here either.


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.
Expand All @@ -1716,6 +1723,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte
/*literal*/ constant String missingInnerMessage;
\end{lstlisting}\end{synopsis}
\begin{semantics}
Allowed for class annotations.
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 Down Expand Up @@ -1767,7 +1775,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte
/*literal*/ constant Boolean defaultConnectionStructurallyInconsistent;
\end{lstlisting}\end{synopsis}
\begin{semantics}
Allowed for model and block class definitions.
Allowed for model and block class annotations.
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 Down Expand Up @@ -2114,6 +2122,7 @@ \subsection{Version Handling}\label{version-handling}
/*literal*/ constant String version;
\end{lstlisting}\end{synopsis}
\begin{semantics}
Allowed for class annotations of top-level classes.
\lstinline!version = $\mathit{currentVersion}$! defines the version number of the model or package.
The $\mathit{currentVersion}$ shall be a \lexicalunitref{PACKAGE-VERSION}.
All classes within this top-level class have this version number.
Expand Down Expand Up @@ -2146,6 +2155,7 @@ \subsection{Version Handling}\label{version-handling}
| "{" PACKAGE-VERSION { "," PACKAGE-VERSION } "}"
\end{lstlisting}\end{synopsis}
\begin{semantics}
Allowed for class annotations of top-level classes.
\lstinline!conversion(noneFromVersion = $\mathit{fromVersion}$)!\annotationindex{noneFromVersion} defines that models and packages using the $\mathit{fromVersion}$ can be upgraded to the $\mathit{currentVersion}$ of the current class without any changes.

\lstinline!conversion(from(version = $\mathit{fromVersions}$, to = $\mathit{toVersion}$, $\mathit{conversionRules}$))! defines that models and packages using any of the $\mathit{fromVersions}$ can be upgraded to the $\mathit{toVersion}$ (if the $\mathit{toVersion}$ is omitted, this is the $\mathit{currentVersion}$) of the current class by applying the $\mathit{conversionRules}$.
Expand All @@ -2170,6 +2180,7 @@ \subsection{Version Handling}\label{version-handling}
")"
\end{lstlisting}\end{synopsis}
\begin{semantics}
Allowed for class annotations of top-level classes.
\lstinline!uses($\mathit{otherPackage}$(version = $\mathit{otherPackageVersion}$))! defines that classes within this top-level class use the $\mathit{otherPackageVersion}$ of classes within the top-level class $\mathit{otherPackage}$.

See \cref{version-date-and-build-information} regarding the use of \lstinline!versionBuild! and \lstinline!dateModified!.
Expand Down Expand Up @@ -2454,8 +2465,7 @@ \subsection{Versions in the File System}\label{mapping-of-versions-to-file-syste
\subsection{Version Date and Build Information}\label{version-date-and-build-information}

This section describes annotations that a top-level class can have to specify information associated to the version number.

The \lstinline!versionBuild! and \lstinline!dateModified! annotations can also be specified in the \lstinline!uses! annotation (together with the version number).
Some of the annotations can also be specified in the \lstinline!uses! annotation.

@HansOlsson HansOlsson Jul 8, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Suggested change
Some of the annotations can also be specified in the \lstinline!uses! annotation.
Some of the annotations can also be specified in the \lstinline!uses! annotation, as stated below.

Or something like that.

Compared to the previous text it seemed a bit vague (which ones?)
I understand that since it is given for the specific annotations it is better to only give it there - but make that clear for users.


\begin{nonnormative}
It is recommended that tools do not automatically store \lstinline!versionBuild! and \lstinline!dateModified! in the \lstinline!uses! annotation.
Expand All @@ -2466,6 +2476,7 @@ \subsection{Version Date and Build Information}\label{version-date-and-build-inf
/*literal*/ constant String versionDate
\end{lstlisting}\end{synopsis}
\begin{semantics}
Allowed for class annotations of top-level classes.
\lstinline!versionDate! is the date when the library was released.
This string is updated by the library author to correspond with the version number.

Expand All @@ -2478,6 +2489,7 @@ \subsection{Version Date and Build Information}\label{version-date-and-build-inf
/*literal*/ constant Integer versionBuild
\end{lstlisting}\end{synopsis}
\begin{semantics}
Allowed for class annotations of top-level classes, and in the \lstinline!uses! annotation (together with the version number).
\lstinline!versionBuild! is the optional build number of the library.
When a new version is released \lstinline!versionBuild! should be omitted or \lstinline!versionBuild = 1!.
There might be bug fixes to the library that do not justify a new library version.
Expand All @@ -2497,6 +2509,7 @@ \subsection{Version Date and Build Information}\label{version-date-and-build-inf
/*literal*/ constant String dateModified
\end{lstlisting}\end{synopsis}
\begin{semantics}
Allowed for class annotations of top-level classes, and in the \lstinline!uses! annotation (together with the version number).
\lstinline!dateModified! is the date and time of the last modification of the package.

The date and time shall given as UTC according to ISO 8601 (with one space between date and time): YYYY-MM-DD hh:mm:ssZ
Expand All @@ -2512,6 +2525,7 @@ \subsection{Version Date and Build Information}\label{version-date-and-build-inf
/*literal*/ constant String revisionId
\end{lstlisting}\end{synopsis}
\begin{semantics}
Allowed for class annotations of top-level classes.
\lstinline!revisionId! is a tool specific revision identifier possibly generated by a source code management system (e.g., Subversion or CVS).
This information exactly identifies the library source code in the source code management system.
\end{semantics}
Expand Down
18 changes: 11 additions & 7 deletions chapters/functions.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1080,7 +1080,7 @@ \section{Derivatives and Inverses of Functions}\label{derivatives-and-inverses-o
"=" UNSIGNED-INTEGER
\end{lstlisting}\end{synopsis}
\begin{semantics}
This annotation has only an effect within a function declaration.
Allowed for function class annotations.

{\lstinline!smoothOrder!} defines the number of differentiations of the function, in order that all of the differentiated outputs are continuous provided all input arguments and their derivatives up to order {\lstinline!smoothOrder!} are continuous.

Expand Down Expand Up @@ -1123,7 +1123,7 @@ \section{Derivatives and Inverses of Functions}\label{derivatives-and-inverses-o
| "zeroDerivative" = IDENT
\end{lstlisting}\end{synopsis}
\begin{semantics}
This annotation has only an effect within a function declaration.
Allowed for function class annotations.

The {\lstinline!derivative!} annotation can influence simulation time and accuracy, can be applied to both functions written in Modelica and to external functions, and may be used several times for the same function declaration.

Expand All @@ -1144,7 +1144,8 @@ \section{Derivatives and Inverses of Functions}\label{derivatives-and-inverses-o
IDENT "=" type-specifier function-call-args"
\end{lstlisting}\end{synopsis}
\begin{semantics}
A function with one output formal parameter may have one or more {\lstinline!inverse!} annotations to define inverses of this function.
Allowed for function class annotations when the function has exactly one output formal parameter.

@HansOlsson HansOlsson Jul 8, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

A side-note: At some point we might want to generalize inverses to multiple outputs - but not now. As I understand it one issue is the syntax.

The function may have one or more {\lstinline!inverse!} annotations to define inverses of this function.

For details abouts using the {\lstinline!inverse!} annotation, see \cref{using-the-inverse-annotation}.
\end{semantics}
Expand Down Expand Up @@ -1677,7 +1678,7 @@ \section{Function Inlining and Event Generation}\label{function-inlining-and-eve
/*literal*/ constant Boolean Inline;
\end{lstlisting}\end{synopsis}
\begin{semantics}
Has only an effect within a function declaration.
Allowed for function class annotations.

If {\lstinline!Inline = true!}, the model developer proposes to inline the function.
This means, that the body of the function is included at all places where the function is called.
Expand All @@ -1697,7 +1698,7 @@ \section{Function Inlining and Event Generation}\label{function-inlining-and-eve
/*literal*/ constant Boolean LateInline;
\end{lstlisting}\end{synopsis}
\begin{semantics}
Has only an effect within a function declaration.
Allowed for function class annotations.

If {\lstinline!LateInline = true!}, the model developer proposes to inline the function after all symbolic transformations have been performed.

Expand Down Expand Up @@ -1728,7 +1729,7 @@ \section{Function Inlining and Event Generation}\label{function-inlining-and-eve
/*literal*/ constant Boolean InlineAfterIndexReduction;
\end{lstlisting}\end{synopsis}
\begin{semantics}
Has only an effect within a function declaration.
Allowed for function class annotations.

If {\lstinline!true!}, the model developer proposes to inline the function after the function is differentiated for index reduction, and before any other symbolic transformations are performed.
The default is to not perform this specific inlining.
Expand All @@ -1742,7 +1743,7 @@ \section{Function Inlining and Event Generation}\label{function-inlining-and-eve
/*literal*/ constant Boolean GenerateEvents;
\end{lstlisting}\end{synopsis}
\begin{semantics}
Has only an effect within a function declaration.
Allowed for function class annotations.

By default, {\lstinline!GenerateEvents = false!} and expressions in the function body that would normally be event generating shall not generate events, similar to inlining the function body while wrapping all expressions in {\lstinline!noEvent!}, see \cref{modelica:noEvent}.
By specifying {\lstinline!GenerateEvents = true!}, event-generating expressions in the function body shall generate events as normal, similar to inlining the function body without wrapping all expressions in {\lstinline!noEvent!}.
Expand Down Expand Up @@ -2301,6 +2302,7 @@ \subsection{Annotations for External Functions}\label{annotations-for-external-l
\end{lstlisting}
\end{synopsis}
\begin{semantics}
Allowed for {\lstinline!external!}-clauses.
{\lstinline!Library = "libraryName"!} is used to tell the linker to include the library file where the compiled external function is available.

{\lstinline!Library = {"libraryName1", "libraryName2"}!} is used to tell the linker to include the library file where the compiled external function is available, as well as additional libraries used to implement it.
Expand Down Expand Up @@ -2382,6 +2384,7 @@ \subsection{Annotations for External Functions}\label{annotations-for-external-l
/*literal*/ constant String LibraryDirectory
\end{lstlisting}\end{synopsis}
\begin{semantics}
Allowed for {\lstinline!external!}-clauses.
The {\lstinline!annotation(LibraryDirectory="modelica:/TopPackage/Resources/Library")!}, used to specify a location for library files.
The preceding one is the default and need not be specified; but another location could be specified by using an URI name for the library directory, see \cref{external-resources}.
Different versions of one object library can be provided (e.g., for Windows and for Linux) by providing a \emph{platform} directory below the {\lstinline!LibraryDirectory!}.
Expand Down Expand Up @@ -2427,6 +2430,7 @@ \subsection{Annotations for External Functions}\label{annotations-for-external-l
/*literal*/ constant String SourceDirectory
\end{lstlisting}\end{synopsis}
\begin{semantics}
Allowed for {\lstinline!external!}-clauses.
The {\lstinline!annotation(SourceDirectory="modelica:/TopPackage/Resources/Source")!}, gives the location for source files.
The preceding one is the default and need not be specified; but another location could be specified by using an URI name for the source directory, see \cref{external-resources}.
It is not specified how they are built.
Expand Down
2 changes: 1 addition & 1 deletion chapters/inheritance.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1317,7 +1317,7 @@ \section{Selective Model Extension}\label{selective-model-extension}\index{desel
for i in 2:10 loop
connect( // This comment does not impact syntactic equivalence.
a[i],
b[2*i] /* Without whitespace in the indexing expression. */ );
b[2*i] /* Without white-space in the indexing expression. */ );

@HansOlsson HansOlsson Jul 8, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

I was unsure if that was needed, and searched for "white-space vs whitespace" which gave:

And the CoPilot summary:

Use "whitespace" as a single word in computing contexts and "white space" as two words in typography or general design.

Usage in Computing
In programming and computer science, "whitespace" refers to characters that create blank space in text, such as spaces, tabs, and line breaks. These characters affect text layout but are not visible themselves, and the term is typically written as a single word when used attributively, for example, "whitespace character" or "remove whitespace from a string"
Standards like the HTML and CSS specifications consistently use "whitespace" to refer to these characters

(Later note: That summary wasn't fully correct, HTML talks about "whitespace", but CSS 2.1 discusses "white space" while the property is called "white-space". CSS 1 also had the property "white-space" - but discussed "whitespace". It could even be that hyphen in the property-name is to make it easier to discuss whitespace as a concept vs. the property white-space.)

Thus I think we might as well keep "whitespace".

Suggested change
b[2*i] /* Without white-space in the indexing expression. */ );
b[2*i] /* Without whitespace in the indexing expression. */ );

end for;
else
for i in 20:30 loop
Expand Down