Code folding not always works

[ceraolo]

from time to time I come across models in which code is not folded. I cannot envisage when this occurs.
I have just an example showing the issue, which I cannot simplify, since when I try the issue is not there anymore.
I attach the example in the file FoldingIssue.mo. Annotations do not fold in "SubPkg.NotFoldingModel"

Moreover, it seems that code folding is not applied whenever line wrapping is disabled. I think the two options should be applicable independently, as it is hinted also in the way they are proposed in Tools|Options|Text editor window.

Tested on the following (Win) version:

OMEdit v1.12.0-dev-40-g0af374d (64-bit) Connected to v1.12.0-dev-54-gc3e6c1b (64-bit)

[adeas31]

The folding only works for multi-line annotations.
The latest omc generates the annotations on multiple lines by default.

[ceraolo]

ah.
I understand.

Maybe code folding can be explained a bit more in the documentation? To tell "enable Code folding" says nothing more than the name of the setting "Enable code folding" I would expect to read there what code folding is and how it works.

This is a more general consideration. In a lot of places the OMEdit documentation is too concise or just replicates the command name. Consider for instance

• Line Ending - Sets the file line ending
• Indent Size – Sets the indent size
• Font Size – Sets the font size.
• etc. etc.

I understand that this is due to the fact that documentation is somewhat automatically generated.
But there are cases in which this is insufficient. My practical experience is that hardly ever I can find useful information in the OMEdit documentation, while a message to the OM forum or here resolves immediately.

I suppose that something could be done to improve the situation (I know so little about how this documentation is generated to envisage something more concrete)

Thank you for your fast response.

[adeas31]

From my point of view (as a developer) a lot of these things are self explanatory. Everyone in the world knows what is Line Ending, Indentation, font size etc.

Perhaps from the users point of view we might need to explain a bit more. Since this particular information is not auto generated so you can contribute to make it better.

Update ​documentation and make a pull request. The documentation is wriiten in ​Sphinx

[ceraolo]

I could easily propose some enhancements that file, depending on how much time requires installing and getting to use Spinx. The first half-our has not been very fruitfuL. In fact, my Windows defender does not accept opening the download files I got from ​https://pypi.python.org/pypi/Sphinx#downloads because it finds there some malware!
Maybe I will have the chance of making another attempt in a few days.

[adeas31]

Well you can edit the file in any text editor. Just make sure you use the sphinx coding syntax. If you try to build documentation on your machine then you have to install a lot of dependencies.

[ceraolo]

ok. I can also see the result using online Sphinx editor.
In the very beginning of help you wrote that OMEdit its written using Qt 4.8, which I think is not valid anymore.
Can you tell me which qt version is used now?
BTW, you told me some weeks ago that you planned to upgrade Qt to 5.7 or 5.8 before OM 1.12 release, so that the known bug in the browser tree disappears. Can you give to me updated information on this also?

[adeas31]

We are using Qt 5.6 now but I guess we should not write the version as it will change soon. Perhaps just write that its written using Qt.

Adrian when will we switch to Qt 5.7?

[ceraolo]

Replying to adeas31:

From my point of view (as a developer) a lot of these things are self explanatory. Everyone in the world knows what is Line Ending, Indentation, font size etc.

Exactly so. A lot of settings are self-explanatory.
Since OMEdit has a lot of settings, dropping those that are self-explanatory from the description will ease the search for information regarding those which need some additional words in the Help.
.

Perhaps from the users point of view we might need to explain a bit more. Since this particular information is not auto generated so you can contribute to make it better.

Update ​documentation and make a pull request. The documentation is wriiten in ​Sphinx

Before making any pull request I would like tho show you how the help would look like when all parts which do not add anything to the controls' names are dropped. See below a sample.
Note that in my view any time it results that some comment must be added to a control, the corresponding part is to be put again in the help, with the new comment.

Let me know. In case it is agreed that this way is acceptable, I could contribute with more stuff.

Below an excerpt from the Sphinx source code, modified according to the above concept

Settings

---

OMEdit allows users to save several settings which will be remembered
across different sessions of OMEdit (see Preserve User's GUI Customizations" below under "General" heading). The Options Dialog can be used for
reading and writing the settings.

In the following, additional information is supplied only when the settings are not self-explanatory.

.. _omedit-settings-general :

General
~

• General

• *Preserve User’s GUI Customizations* – If true then OMEdit will

remember its windows and toolbars positions and sizes across different sessions.

• *Hide Variables Browser* – Hides the variable browser when switching away from plotting perspective.

• Default View

• *Icon View/DiagramView/Modelica Text View/Documentation View* – If no

preferredView annotation is defined then this setting is used to show
the respective view when user double clicks on the class in the
Libraries Browser.

• Enable Auto Save

• *Auto Save interval* – Sets the auto save interval value. The minimum

possible interval value is 60 seconds.

Libraries
~

• *System Libraries* – The list of system libraries that should be loaded every time OMEdit starts.

• *Force loading of Modelica Standard Library* – If true then Modelica and ModelicaReference will always load even if user has removed them from the list of system libraries.

• *Load OpenModelica library on startup* – If true then OpenModelica package will be loaded when OMEdit is started.

• *User Libraries* – The list of user libraries/files that should be loaded every time OMEdit starts.

Text Editor
~

• Syntax Highlight and Text Wrapping

• *Enable Code Folding* - Enable/Disable the code folding. When code folding is enabled multi-line annotations are collapsed into a compact icon (a rectangle containing "...)"). A marker containing a "+" sign becomes available at the left-side of the involved line, allowing the code to be expanded/re-collapsed at will,

Modelica Editor
~

• *Preserve Text Indentation* – If true then uses *diffModelicaFileListings* API call otherwise uses the OMC pretty-printing.

[adeas31]

I don't like the idea of dropping the already available documentation. What's self-explanatory for me is not self-explanatory for you. Similarly what's self-explanatory for you is probably not self-explanatory for someone else.

So keep the existing and add new information is the way to go.

[ceraolo]

Replying to adeas31:

I don't like the idea of dropping the already available documentation. What's self-explanatory for me is not self-explanatory for you.

I proposed to drop only things for which the explanation just repeats the name of the control. This way it adds nothing.
Just clutters the documentation making more difficult to find actual content.

But it's your software, not mine...

[adeas31]

I mean skipping over things like,

Language – Sets the application language.
Working Directory – Sets the application working directory.
Toolbar Icon Size – Sets the size for toolbar icons.

is not nice. I would recommend to keep them.

So what I can see from source above you just want this to be in the documentation,

*Enable Code Folding* - Enable/Disable the code folding. When code folding is enabled multi-line annotations are collapsed into a compact icon (a rectangle containing "...)"). A marker containing a "+" sign becomes available at the left-side of the involved line, allowing the code to be expanded/re-collapsed at will,

I will add this. Do you some more suggestions?

[ceraolo]

If you like this way, for me it is ok.
But let me insist a little more.
Do you really want to keep a list of controls in which you, as documentation, just repeat the control name (as in the examples in your comment 13)?
This is something like automatic documentation software does, but when a human has a chance of working on documentation he can do better.
Having a help full of such use-less rows, dilutes the information that really a user might appreciate.

I repeat, it is up to you, but it looks like, being a full-time programmer, you began to like things as they are written by computers, not humans... :-)

However, In case I have any further addition to recommend I will do.

[adeas31]

I updated the OMEdit documentation ​https://openmodelica.org/doc/OpenModelicaUsersGuide/latest/omedit.html