DocumentationClass annotation

[modelica-trac-importer]

Reported by otter on 3 Apr 2013 15:11 UTC
In MSL there is currently a vendor specific annotation to mark documentation classes. The question is whether this annotation should be standardized or should be removed. In case this annotation should be standardized, it might be defined in the following way:

DocumentationClass = true

Has only an effect on a class annotation and defines that this class and all classes within this class are "documentation classes" that solely shall present information. In particular this means that the class with this annotation and all classes within it

• have an implicit annotation preferredView="info", and
• cannot be dragged from the package browser.

[A tool may display documentation classes in a special way in the package browser. 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.]

The major benefit of this annotation will be that a library developer needs to define it only once at the top level of a documentation hierarchy (like Modelica.UsersGuide or ModelicaReference). If this annotation is not present, a library developer has to define preferredView = "info" on all documentation classes, in order that clicking on a class or clicking on a link to this class opens the info layer and not any other layer (which is in nearly all cases not useful). It is very unlikely that it is possible to consistently guarantee that such an annotation is set because it is not possible to practically test it (with exception of a script that with some heuristics checks this automatically). Additionally, it gives a vendor a simple possibility to display such type of documentation in a different form as "usual" classes.

An alternative could be that a vendor deduces the "DocumentationClass" property from other information, for example from inherited classes. However, this is not recursive, is a bit indirect, and the super classes may change over time, so this is a heuristics that may fail (e.g. currently Modelica.Icons.Information, .ReleaseNotes, .Contact, .References are used as super classes for documentation classes).

---

Migrated-From: https://trac.modelica.org/Modelica/ticket/1062

[modelica-trac-importer]

Modified by dietmarw on 3 Apr 2013 15:22 UTC

[modelica-trac-importer]

Comment by eshmoylova on 3 Apr 2013 15:46 UTC
Martin, I think you forgot to add the link to the foodle poll. Adding it just so that we have it here in this discussion.
https://tester.dfn.de/foodle/DocumentationClass-51516#responses
Also copied-and-pasted Mike Tiller's email response about his vote.

All,
I admit that I am not so familiar with this issue. When the poll was raised, I looked at the definition for the annotation and it seemed reasonable. In particular, preferredView does not quite go so far as to convey that the entire package is really documentation and it seemed to save a lot of work in having to put preferredView on all nested definitions.
HOWEVER, I would argue, looking at the results, that a reasonable course of action would be to not (yet) standardize it, remove it from the MSL so that we can have a truly compliant MSL and then consider the issue of standardization of this annotation afterwards. This is perfectly fine by me.

I did not intend my poll answer to be interpreted as "I insist that it be standardized before the next MSL release".
I hope that clarifies things.

--
Mike

[modelica-trac-importer]

Comment by stefanv on 3 Apr 2013 16:04 UTC
An automatically recursive way to define that something is a documentation class makes it impossible to include usable sample models within the documentation.

Adding DocumentationClass to 3.2rev2 is non-backward compatible with 3.2, and my understanding was that 3.2 rev1 and rev2 were to be clarifications only.

[modelica-trac-importer]

Comment by dzimmer on 3 Apr 2013 16:16 UTC
Alright my two cents:

1. Without doubt, there are certain advantages to treat documentation classes in a special way. But this is not the question. The question is: Do we need an extra annotation to find out whether a class shall be treated as documentation class or not. I do not think that this is required but it is up to the tool vendors to answer this question. I think that any tool can determine the preferred view easily while parsing it and hence we should remove redundancy from the language

2. What is the design strategy? First we unify things by including the doc-files in regular Modelica packages and then we introduce an annotation to de-unify things that we have unified before? If documentation packages really require such a special treatment then there should be a separate Modelica class for them.

[modelica-trac-importer]

Comment by leo.gall on 3 Apr 2013 17:21 UTC
My comments:

1. The recursive behavior of this annotation should be visible to the user. Why is the annotation called DocumentationClass instead of DocumentationPackage?

Proposal for packages with annotation DocumentationPackage = true:

• general classes within this package will have the special behavior as proposed in this ticket
• models, blocks, functions and records could be excluded (so that examples can be embedded in a user guide, as proposed by Stefan V.)

2. I tend to agree with Dirk's item 2): If documentation classes need special treatment, then maybe a specialized class would be the better solution?

3. Probably the proposed annotation isn't needed and it's only a tool issue for library developers: I would prefer a tool helping me to set the preferredView annotations correctly. For example:

• Go through my library and add annotation preferredView="info" to all classes extending Modelica.Icons.Information.
• Go through my library and set all functions to preferredView="info"

[modelica-trac-importer]

Comment by otter on 4 Apr 2013 08:39 UTC
Replying to [comment:3 stefanv]:

An automatically recursive way to define that something is a documentation class makes it impossible to include usable sample models within the documentation.

The current way in all Modelica libraries (MSL, other free libraries and all the commercial libraries) is to have this separate, that is, have a hierarchical !UsersGuide package and have running examples in Examples packages in a different hierarchy. There are links from the !UsersGuide to the Examples. I do not see a good reason why this structuring should be changed.

Adding DocumentationClass to 3.2rev2 is non-backward compatible with 3.2, and my understanding was that 3.2 rev1 and rev2 were to be clarifications only.

No.

Backwards compatible means that models that are already available, will also run with MSL 3.2.1 (specification 3.2 rev. 2). It does not mean that models based on MSL 3.2.1 will run in previous environments for MSL 3.2 (specification 3.2 rev. 1).

Renaming the existing __Dymola_DocumentationClass annotation to DocumentationClass is exactly the same approach as used for about 15 other vendor specific annotations and these annotations are documented in specification 3.2 rev. 2, see ticket #786.

The major goal of Modelica 3.2 rev 2 is that MSL 3.2.1 and the specification are in full agreement. For this to happen, a few new features have to be added to rev. 2 (rooted operator, calling functions via an instance, new annotations), and one feature needs to be removed (Mapping of Models to Execution Environment).

[modelica-trac-importer]

Comment by pharman on 4 Apr 2013 09:13 UTC
The issues I see with DocumentationClass, and the reason I disagree with adding it, are:

• It doesn't provide information that can't be specified or derived in other ways
• The description makes the assumption that all Modelica tools have the same UI concepts, I don't agree that UI features beyond the diagram and icon should be specified (and yes, there are already plenty of annotations that break this)
• Since we have URLs to resources in the Modelica path there are ways of providing hyperlinked documentation as part of a library, other than a hierarchy of classes containing only documentation

[modelica-trac-importer]

Comment by mtiller on 4 Apr 2013 12:54 UTC
I think Pete's assessment is a good one.

[modelica-trac-importer]

Comment by stefanv on 4 Apr 2013 13:38 UTC
Replying to [comment:6 otter]:

Replying to [comment:3 stefanv]:

An automatically recursive way to define that something is a documentation class makes it impossible to include usable sample models within the documentation.

The current way in all Modelica libraries (MSL, other free libraries and all the commercial libraries) is to have this separate, that is, have a hierarchical !UsersGuide package and have running examples in Examples packages in a different hierarchy. There are links from the !UsersGuide to the Examples. I do not see a good reason why this structuring should be changed.

I have found no specification that says that a library must adhere to this sort of structure.

[modelica-trac-importer]

Comment by otter on 4 Apr 2013 21:32 UTC
Replying to [comment:7 pharman]:

The issues I see with DocumentationClass, and the reason I disagree with adding it, are:

• It doesn't provide information that can't be specified or derived in other ways

Please, give more information.

As sketched above, the only way that I currently see is that a tool has a heuristic that if a class is derived from certain superclasses, it assumes that then the Documentation property holds. However, if another superclass with another icon is introduced by library developers, then this heuristics does not work. So this is not a reliable solution.

Another approach would be to include the preferredView annotation at all places. However, this does not give the property "should not be dragged", and it replaces a few definitions with one or two order of magnitudes more definitions.

Please, explain, if you meant with your statement "cannot be specified or derived in another way" the two proposals above (that have significant drawbacks), or if you have other ideas.

• The description makes the assumption that all Modelica tools have the same UI concepts, I don't agree that UI features beyond the diagram and icon should be specified (and yes, there are already plenty of annotations that break this)
• Since we have URLs to resources in the Modelica path there are ways of providing hyperlinked documentation as part of a library, other than a hierarchy of classes containing only documentation

I agree that the UI concept should be left to the tools as much as possible. However, the information for the UI must be provided in a library and how this information is provided must be standardized. There was a long discussion 10 years ago how this should be done (one proposal was to have all info/icon features in separate files) and at that time it was decided to include all such information with annotations in a model (the reasons have been, (a) to be better integrated and (b) less critical to keep things consistent to each other). Unless there is a new discussion with a different decision, MSL will be developed in this spirit, and this means that overall, tutorial information, as well model/icon specific information will be included as annotations in the library. Of course, if there are better ideas to improve the documentation, we can change this. But I do not have seen yet a proposal of this kind.

Now, if documentation stays with annotations, as an extreme example see ModelicaReference consisting of documentation only, then the UI can be improved if this is specially marked.

You say all this annotation information is not necessary for a UI. This is new to me. Of course the library developer has a certain view on parameters (so group/tab annotations, choices annotations, etc.). If the library developer expresses his structuring concept, then this has to be specified with annotations (but a tool has of course a lot of freedom to present this structuring to the user). Otherwise, either the tool makes it somehow automatic (but then sub-optimal from a library developer perspective), or the tool has to add additional information by itself (again sub-optimal from a library developer and a lot of work). To summarize, please give more information since otherwise it is not possible to understand your generic statement "there are already plenty of annotations that break this".

O.k. going back to the source of the problem: Release of MSL 3.2.1:
Since a long time there are Dymola_DocumentationClass annotations in the library. Dymola is using this vendor-specific annotation to improve the UI for its end-users. Removing this annotation completely then just means that the UI for a new Dymola release is less user convenient as before. I do not think that this is fair and the Modelica Assocation should not act in a way to remove features that a vendor already provides to its end-users since many years (just to be clear: vendor specific annotations are standardized and therefore having vendor specific annotations in MSL is compliant to the Modelica Specification). Therefore, I currently only see the following options:

1. Keep it as it is, that is keep this vendor specific annotation that marks Documentation classes.
2. Remove this vendor-specific annotation and instead introduced preferredView="Info" annotations in all Documentation classes.
3. Standardize the "marking" of a Documentation package somehow (either with an annotation, a new class definition, or in another way).

All these options have their drawbacks. If you still have another proposal, please explain.

[modelica-trac-importer]

Comment by otter on 4 Apr 2013 21:54 UTC
Replying to [comment:9 stefanv]:

Replying to [comment:6 otter]:

Replying to [comment:3 stefanv]:

An automatically recursive way to define that something is a documentation class makes it impossible to include usable sample models within the documentation.

The current way in all Modelica libraries (MSL, other free libraries and all the commercial libraries) is to have this separate, that is, have a hierarchical !UsersGuide package and have running examples in Examples packages in a different hierarchy. There are links from the !UsersGuide to the Examples. I do not see a good reason why this structuring should be changed.

I have found no specification that says that a library must adhere to this sort of structure.

I did not say that this is a requirement, but just that this is how current libraries are structured.

In the EUROSYLIB project where > 30 Modelica libraries have been developed, there was also one task to setup guidelines for new libraries. Such guidelines have been also discussed in the Modelica Association at various circumstances. Furthermore, several organizations developing libraries have their internal guidelines (probably the most advanced ones are the ones from Modelon). To my knowledge, all of these guidelines use the above structuring. However, these guidelines are different in other aspects, and I think it was never possible to agree on one set of guidelines within the Modelica Association.

I do not say that we should restart this discussion about library guidelines, since it is difficult to get agreement and it takes a lot of time and the actual benefit with respect to the current situation is not clear to me. For your information I have stored the EUROSYSLIB guidelines (with some extensions later performed by DLR) on the svn server under !https://svn.modelica.org/projects/Modelica/branches/development/LibraryTemplate

[modelica-trac-importer]

Comment by anonymous on 5 Apr 2013 08:37 UTC
Replying to [comment:10 otter]:

Replying to [comment:7 pharman]:

O.k. going back to the source of the problem: Release of MSL 3.2.1:
Since a long time there are Dymola_DocumentationClass annotations in the library. Dymola is using this vendor-specific annotation to improve the UI for its end-users. Removing this annotation completely then just means that the UI for a new Dymola release is less user convenient as before. I do not think that this is fair and the Modelica Assocation should not act in a way to remove features that a vendor already provides to its end-users since many years (just to be clear: vendor specific annotations are standardized and therefore having vendor specific annotations in MSL is compliant to the Modelica Specification). Therefore, I currently only see the following options:

1. Keep it as it is, that is keep this vendor specific annotation that marks Documentation classes.
2. Remove this vendor-specific annotation and instead introduced preferredView="Info" annotations in all Documentation classes.
3. Standardize the "marking" of a Documentation package somehow (either with an annotation, a new class definition, or in another way).

All these options have their drawbacks. If you still have another proposal, please explain.

I agree that we should not wilfully destroy the usability of an existing product. I would expect that the people from Dynasim can actually answer this question best. Here is what I (as regular Dymola user) think about it.

From your options, I would favor no. 2 for the following three reasons:

1. The preferred view is the most important functionality and can be saved in this way.

2. For me, as regular Dymola user, the existing Drag&Drop protection is a disadvantage. Please consider that there is already (a very well implemented) Drag&Drop protection for regular packages (you can not place them in the model-diagram). However when in text editing mode, I can conveniently refer to a package name by Drag&Drop. I cannot do that if the package is a documentation class but these are the classes that I want to refer to most often when in text-mode. For me this is a disadvantage. I would favour if doc-classes are handled exactly as all other packages w.r.t Drag&Drop.

3. Enforcing the constraint that a doc-class can only contain doc-classes and nothing else is according to some (important) guidelines but not according to the spec. I think that the spec is what matters and I do not see currently a majority in our community to change the spec in this regard.

[modelica-trac-importer]

Comment by dzimmer on 5 Apr 2013 08:43 UTC
Sorry for the anonymous post. That was me

[modelica-trac-importer]

Comment by jmattsson on 8 Apr 2013 07:57 UTC
Replying to [comment:11 otter]:

I did not say that this is a requirement, but just that this is how current libraries are structured.

That does not necessarily mean that it is the best was to do it, just that it is a convenient way in Dymola.

Since most existing libraries are written with Dymola, we can't really use such arguments when deciding if a feature of Dymola should be standardized.

There was one additional thing in the original suggestion for the poll that is missing here - that the description of the class is used instead of the name in the package browser (or equivalent, I guess). I think that is a bad idea, but should be mentioned, since it was a part of the poll.

[modelica-trac-importer]

Comment by volker.beuter on 11 Apr 2013 22:10 UTC
I agree with Hans and Martin that a special treatment of documentation classes besides
displaying the documentation text by default (using documentation string instead of class
name, disabling drag & drop) is an advantage.

On the other hand I also agree it is a good practice to collect documentation in one package and put examples into another but that this is not prescribed by the specification and should not be done. A library developer ought to be free to put examples within a documentation package. But we could escape this by adding rule that a class within a documentation class is not regarded a documentation class itself if it has some other content e.g. a non-empty equation or algorithm section.

No vendor is forced to support such an annotation and may simply ignore it. So as a compromise we may add DocumentationClass as a standard annotation to the spec (and keep on using it in the MSL) but also add the preferredView="info" annotation to all classes currently using DocumentationClass and also to all classes within. So any tool is free to stick to the annotation it supports.

An argument against Leo Galls suggestion to call the annotation DocumentationPackage instead is that it should also be possible to declare a single class to be a documentation class. I also do not agree to his and Dirk´s idea that a special Modelica class for documentations might be better than an annotation: A tool vendor is free to ignore a new annotation DocumentationClass, but would be forced to support some new special class or / and special package (also involving a new keyword). (And I also absolutely do not like the idea a tool may "help" me by adding any annotations automatically, but this is quite another issue ... )

I think it a a great achievement to store the documentation of a class within that class instead of in
some other file where it can get lost at copying or moving action. This we should not give up.

To summarize my arguments: I propose to standardize the DocumentationClass annotation with the additional rule that a class contained in a documentation class is only considered a documentation class itself if it does not contain any other content (or that only classes and packages of documentation classes are considered documentation classes itself, but not models, functions, records etc. like Leo Gall suggested) in order to admit examples within documentation packages.

[modelica-trac-importer]

Comment by hansolsson on 19 Apr 2013 15:31 UTC
An alternative if people do not want to standarize DocumentationClass:

I realized that there is a simple variant for how to make the package browser work as intended (see below for examples) for documentation-classes by a small change of Dymola (and other tools) and MSL; no change of the specification is needed.

Idea: If the class-name is in single-quotes we unquote it and use the unquoted name in the browser; preferably with a different font (italic or bold, or even color) – the font change avoids some confusion. We then use quoted names consistently for User's Guide packages.

So basically package 'User\'s Guide' ... will give User's Guide (italics intended) in the browser.

In addition tools should ideally have some way of adding preferredView="Info" recursively in a sub-tree.

The general drag'n'drop-blocking is gone in this case.
---
The rest is examples extracted from a previous mail:
---
The following is a list of the browser names of Modelica.UsersGuide that cannot be class names (class name in brackets):

• User’s Guide [UsersGuide]
• Overview of Modelica Library [Overview]
• HTML documentation [Documentation]
• Modelica code [ModelicaCode]
• Naming convention [Naming]
• User’s Guide [UsersGuide]
• Implementation notes [Implementation]
• Revision History [RevisionHistory]
• Parameter defaults [ParameterDefaults]
• Modelica License 2 [ModelicaLicense2]
• Release notes [ReleaseNotes]
• Version Management [VersionManagement]
• Version 3.2 with bug fixes [Version_3_2_Bugfixes]
• Version 3.2 (Oct 25, 2010) [Version_3_2]
• Version ...
  (and similarly for other packages like Modelica.Fluid.UsersGuide).

[modelica-trac-importer]

Comment by sjoelund.se on 22 Apr 2013 18:29 UTC
Also, any names with non-ascii characters cannot be used as identifiers. The class comments are also allowed to be html, which identifiers cannot (although that would be an easy change... identifiers are allowed to be html; they are just not treated as it by default).
package '<html><em>&degC</em></html>' ... would work as I do not really like changing fonts by default in the browser.

Note that one really annoying part is that in order to link using modelica:// you would now need to know the release date of Version 3.2, (or full html tag), etc. I am not very fond of this solution. On the other hand, I am not fond of any of them.

[modelica-trac-importer]

Comment by otter on 15 May 2013 12:22 UTC
I changed the milestone from Modelica 3.2rev2 to MSL3.2.1 in order that this ticket appears in the MSL list for version 3.2.1 to come to a conclusion what to do in MSL 3.2.1

[modelica-trac-importer]

Comment by otter on 15 May 2013 12:27 UTC
Replying to [comment:17 sjoelund.se]:

Also, any names with non-ascii characters cannot be used as identifiers. The class comments are also allowed to be html, which identifiers cannot (although that would be an easy change... identifiers are allowed to be html; they are just not treated as it by default).
package '<html><em>&degC</em></html>' ... would work as I do not really like changing fonts by default in the browser.

Note that one really annoying part is that in order to link using modelica:// you would now need to know the release date of Version 3.2, (or full html tag), etc. I am not very fond of this solution. On the other hand, I am not fond of any of them.

I do not understand your last comment: The name of the class would be "Version 3.2 (Oct 25, 2010)" instead of "Version_3_2". In both cases it is not sufficient to just know the version number, but know the logic how the class name is build from it. So the best is anyway to just look at the class and copy the class name. 

[modelica-trac-importer]

Comment by sjoelund.se on 15 May 2013 12:45 UTC
Compare:
modelica://Modelica.UsersGuide.ReleaseNotes.Version_3_2
To:
modelica://Modelica.'User's Guide'.'Release notes'.'Version 3.2 (Oct 25, 2010)'

That is why I don't like the prospect of having the description string being the class name.

[modelica-trac-importer]

Comment by jmattsson on 15 May 2013 15:13 UTC
Replying to [comment:20 sjoelund.se]:

modelica://Modelica.'User's Guide'.'Release notes'.'Version 3.2 (Oct 25, 2010)'

If we want to follow the spec for URIs, then it would even become: modelica://Modelica.%27User%5C%27s%20Guide%27.%27Release%20notes%27.%27Version%203.2%20(Oct%2025%2C%202010)%27

[modelica-trac-importer]

Comment by otter on 22 May 2013 13:30 UTC
Replying to [comment:21 jmattsson]:

Replying to [comment:20 sjoelund.se]:

modelica://Modelica.'User's Guide'.'Release notes'.'Version 3.2 (Oct 25, 2010)'

If we want to follow the spec for URIs, then it would even become: modelica://Modelica.%27User%5C%27s%20Guide%27.%27Release%20notes%27.%27Version%203.2%20(Oct%2025%2C%202010)%27

This is a tool issue. Usually, I never type in a Modelica path name that I want to link, since this is too error prone. Instead, in Dymola I right click on the desired name in the package browser and select "copy path", and then I paste this in to the desired location.

Note, independently of DocumentationClass, the above feature should be supported by a tool, because (a) a classname can be constructed legally in this way, and (b) a class name can be used in a Modelica link.

Since probably no Modelica tool supports the URI characters like %20 currently, we ignore this problem for the moment.

[modelica-trac-importer]

Comment by jmattsson on 22 May 2013 13:44 UTC
Replying to [comment:22 otter]:

Since probably no Modelica tool supports the URI characters like %20 currently, we ignore this problem for the moment.

I'm not sure what you mean by "supports" here. I suspect that most Modelica tools can parse them, since the easiest way to parse an URI is to use a library that does that, and then you get such things for free.

I'm OK with saying that it's fine because the URIs can be constructed by the tool, though.

[modelica-trac-importer]

Comment by otter on 22 May 2013 14:00 UTC
We need to settle this issue with DocumentationClass before releasing MSL 3.2.1. I therefore just had a phone call with Hilding and Hans to discuss the various options summarized in this ticket. There is no perfect solution, but the following compromise seems to be reasonable:

Proposal 1:

1. The __Dymola_DocumentationClass will not be standardized and will be removed from MSL trunk.
2. All documentation classes in MSL trunk will be changed so that the description string is used as class name in apostrophes and the description string is removed.
3. It is of course a tool issue how a class name in apostrophes is displayed in the package browser (e.g. nothing special; or apostrophes are removed and the class name is shown a bit differently as class names without apostrophes, e.g. in italics, other font, other color).
4. It is recommended that "preferredView="Info"" is used as default for packages (this is in general a good idea, not only for Documentation classes).
5. The "leave" nodes of a documentation class (usually "class") get an explicit "preferredView = Info" annotation (a tool can add a heuristics additionally, to have this as default, if the class inherits from a specific icon, like Icons.Information or Icons.Contact, in order to provide a convenient view even if a user forgets to introduce this annotation).

Example:
The User's Guide of MSL would have then the following Modelica definition:

package 'User\'s Guide'    // no description text
   class 'Overview of Modelica Library'  // no description text
       ...
   end 'Overview of Modelica Library';

   package 'Conventions'    // no description text
      package 'HTML documentation'  // no description text
      end 'HTML documentation'
   end 'Conventions'

end 'User\'s Guide';

Note, this means that nothing has to be changed in Modelica 3.2 rev.2 and only the documentation classes in MSL in the trunk needs to be slightly adapted, and this MSL should display reasonably without changes in current tools.

If there are any other proposals that you think are better as the one above, please add them to this ticket with a precise description. In case there are several proposals, we can make an electronic poll in order to see whether consensus can be reached.

[modelica-trac-importer]

Comment by dietmarw on 22 May 2013 15:47 UTC
Some comments:

Replying to [comment:24 otter]:

2. All documentation classes in MSL trunk will be changed so that the description string is used as class name in apostrophes and the description string is removed.

What would be the reason for removing the description string? Duplication of information? The description string can still be handy because it might provide more elaborate information which could be displayed in the mouse-over text. So I'm not sure it's necessary to remove those.

3. It is of course a tool issue how a class name in apostrophes is displayed in the package browser (e.g. nothing special; or apostrophes are removed and the class name is shown a bit differently as class names without apostrophes, e.g. in italics, other font, other color).

Although a tool issue I would recommend not to do this since we already have a couple of '...' classes in Complex which then suddenly would also look like documentation type classes.

5. The "leave" nodes of a documentation class (usually "class") get an explicit "preferredView = Info" annotation (a tool can add a heuristics additionally, to have this as default, if the class inherits from a specific icon, like Icons.Information or Icons.Contact, in order to provide a convenient view even if a user forgets to introduce this annotation).

So why not the same heuristics without having to "uglify" the class names with lots of apostrophes.

So here is a modified:

Proposal 2

1. The __Dymola_DocumentationClass will not be standardized and will be removed from MSL trunk.
2. Documentation classes can keep the description string and the tool can decide (or even better makes this an option) to display the description string instead of the class name.
3. It is recommended that preferredView="info" is used as default for packages (this is in general a good idea, not only for Documentation classes).
4. The "leave" nodes of a documentation class (usually "class") get an explicit preferredView = info annotation (a tool can add a heuristics additionally, to have this as default, if the class inherits from a specific icon, like Icons.Information or Icons.Contact, in order to provide a convenient view even if a user forgets to introduce this annotation).
5. Make heuristics for the tools easier by introducing the convention that documentation packages can only contain classes of type class and package which also means there can not be any documentation classes of type model, block, etc. (This seems to be already the case within the MSL anyway.).

[modelica-trac-importer]

Comment by otter on 5 Jun 2013 13:40 UTC
Decision at the Modelica Design Meeting

Standardize annotation DocumentationClass:

Only allowed as class annotation on any kind of class and implies that this class and all classes within it are treated as having the annotation preferredView="info".
[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.]

Proposal:
The above definition will be included in Modelica 3.2 rev. 2

Vote:
In favor: 15
Against: 0
Abstain: 2

[modelica-trac-importer]

Comment by otter on 6 Jun 2013 07:10 UTC
Replaced annotation __Dymola_DocumentationClass by DocumentationClass in MSL trunk in r6627.

[modelica-trac-importer]

Changelog modified by otter on 6 Jun 2013 07:10 UTC
Due to standardization of annotation DocumentationClass, all occurences of __Dymola_DocumentationClass are renamed to DocumentationClass

[modelica-trac-importer]

Comment by otter on 14 Jun 2013 08:14 UTC
During testing the MSL on trunk with Dymola 2014 the following issue was detected:

If flag pedantic = false, everything is o.k.If flag pedantic = true, Dymola prints an error message that "the annotation DocumentationClass is not standardized".

This is of course correct, since this annotation was standardized after the release of Dymola 2014.

I discussed this with Hans and the conclusion is:

Keep it as it is and in the next Dymola version this error message will no longer appear.Existing models and libraries are not affected, because they do not use this new annotation.Only when running "check" on MSL this is noticed and then the MSL testers have to go through the error list and ignore the ones with annotation DocumentationClass (or set pedantic = false)

[modelica-trac-importer]

Comment by volker.beuter on 27 Jun 2013 21:27 UTC
The decided text in the specification does not cover all the implications that there have been in the discussion about this annotation. In particular, does a preferredView annotation in a class within it overwrite the DocumentationClass annotation for this class? I think this cannot just be a tool issue because this may determine if a class within a documentation class can be an example (executable top-level model or component model) or not, if a tool handles a documentation class in a way (e.g. by drag & drop-prevention) that it cannot be used in another way than displaying documentation.

[modelica-trac-importer]

Modified by dietmarw on 27 Jun 2013 21:36 UTC

[modelica-trac-importer]

Comment by otter on 3 Jul 2013 12:20 UTC
Replying to [comment:29 volker.beuter]:

The decided text in the specification does not cover all the implications that there have been in the discussion about this annotation. In particular, does a preferredView annotation in a class within it overwrite the DocumentationClass annotation for this class? I think this cannot just be a tool issue because this may determine if a class within a documentation class can be an example (executable top-level model or component model) or not, if a tool handles a documentation class in a way (e.g. by drag & drop-prevention) that it cannot be used in another way than displaying documentation.

Changed the specification text to:
Only allowed as class annotation on any kind of class and implies that this class and all classes within it are treated as having the annotation preferredView="info". If the annotation preferredView is explicitly set for a class, it has precedence over a DocumentationClass annotation. [...].

Will commit the updated specification soon (first inspecting other tickets).

[modelica-trac-importer]

Modified by otter on 25 Jul 2013 13:48 UTC