More consistently describe where an annotation is allowed - #3927
henrikt-ma wants to merge 4 commits into
Conversation
| 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. |
There was a problem hiding this comment.
| 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.
There was a problem hiding this comment.
The entire paragraph introducing this subsection reads like this:
This section describes annotations that a top-level class can have to specify information associated to the version number.
Some of the annotations can also be specified in the \lstinline!uses! annotation.
For me, it goes without saying that it talks about what is stated below, and re-stating this would be ugly.
There was a problem hiding this comment.
I agree that it talks about what is given below. But it isn't obvious that the specific annotations that can be on a uses-annotations are specified below for the specific annotations, and e.g., not listed under the uses-annotation.
Just something like the following may be enough to indicate that the information is included here, and not somewhere else. Something like the following may make that clearer without restating anything:
| Some of the annotations can also be specified in the \lstinline!uses! annotation. | |
| Including whether they can also be specified in the \lstinline!uses! annotation. |
There was a problem hiding this comment.
But it is also stated for the uses-annotation itself, so we don't need this introductory paragraph to explain in detail where to find the information.
I think we need to remember that this is just the informal opening paragraph to the section, the consistent way of describing where each annotation may be used is the real solution to the problem. Would it be better to open the section with a paragraph which doesn't speak at all of where the annotations may be used?
There was a problem hiding this comment.
My first reaction was that it may work; and is preferable to a vague "some of ...". The important part is figuring out why it was added, and see whether it is still relevant.
As far as I can see the relevant issues are:
#2239
#161
It doesn't seem to indicate that it was added due to some clear need for that in itself, but only for what follows.
So, yes, we can remove it:
But, there is a clear need for what follows, and thus line 2461/2471 should clearly be updated as it currently says:
It is recommended that tools do not automatically store \lstinline!versionBuild! and \lstinline!dateModified! in the \lstinline!uses! annotation.
which is odd to add if we haven't stated that any annotations can occur there at all (and also an odd way to introduce the specific ones).
So, if we don't mention them at the start I believe it is best to move&duplicate that line to versionBuild and dateModified.
Additionally:
Line 2175/2186
See \cref{version-date-and-build-information} regarding the use of \lstinline!versionBuild! and \lstinline!dateModified!.
I believe that should be replaced by two separate references, as the changes above would move the text it was referencing.
Co-authored-by: Hans Olsson <HansOlsson@users.noreply.github.com>
Co-authored-by: Hans Olsson <HansOlsson@users.noreply.github.com>
| 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!. |
There was a problem hiding this comment.
| See \cref{version-date-and-build-information} regarding the use of \lstinline!versionBuild! and \lstinline!dateModified!. | |
| See \cref{versionBuild} and \cref{dateModified} regarding the use of \lstinline!versionBuild! and \lstinline!dateModified!, respectively. |
As indicated in https://github.com/modelica/ModelicaSpecification/pull/3927/changes#r3914643884
|
|
||
| \begin{nonnormative} | ||
| It is recommended that tools do not automatically store \lstinline!versionBuild! and \lstinline!dateModified! in the \lstinline!uses! annotation. | ||
| \end{nonnormative} |
There was a problem hiding this comment.
As suggested in https://github.com/modelica/ModelicaSpecification/pull/3927/changes#r3914643884
| In special cases, the \lstinline!uses!-clause of a model may specify \lstinline!versionBuild! and/or \lstinline!dateModified!. | ||
| In such a case the tool is expected to give a warning if there is a mismatch between library and model. |
There was a problem hiding this comment.
| In special cases, the \lstinline!uses!-clause of a model may specify \lstinline!versionBuild! and/or \lstinline!dateModified!. | |
| In such a case the tool is expected to give a warning if there is a mismatch between library and model. | |
| It is recommended that tools do not automatically store \lstinline!versionBuild! and \lstinline!dateModified! in the \lstinline!uses! annotation. |
Based on suggestion in https://github.com/modelica/ModelicaSpecification/pull/3927/changes#r3914643884
| /*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). |
There was a problem hiding this comment.
| Allowed for class annotations of top-level classes, and in the \lstinline!uses! annotation (together with the version number). | |
| Allowed for class annotations of top-level classes, and in the \lstinline!uses! annotation (together with the version number). | |
| For the latter case see \cref{versionBuild}. |
HansOlsson
left a comment
HansOlsson
left a comment
There was a problem hiding this comment.
As noted the dateModified and versionBuild changes are incomplete without updates in other places.
2 participants
This addresses most of a problem I noted when an LLM didn't dare drawing conclusions about where the
missingInnerMessageannotation is allowed.Currently not covered by this PR:
Licenseannotation (three different context, two different value types).