#1147 Add extra type annotations to the iface file format to help plugin writers

[Kasper B. Graversen]

I have been fairly succesful in code generating a lot of code from the "Scintilla.iface" file (eg. https://github.com/kbilsted/NotepadPlusPlusPluginPack.Net/blob/topic/editorgateway_v1/Visual%20Studio%20Project%20Template%20C%23/PluginInfrastructure/ScintillaGateway.cs, https://github.com/kbilsted/NotepadPlusPlusPluginPack.Net/blob/topic/editorgateway_v1/Visual%20Studio%20Project%20Template%20C%23/PluginInfrastructure/Scintilla_iface.cs). There are, however, situations where the present format is not accurat enough for richer languages than C.

Take for example the enu definition and the subsequent gets and sets

enu FontWeight=SC_WEIGHT_
val SC_WEIGHT_NORMAL=400
val SC_WEIGHT_SEMIBOLD=600
val SC_WEIGHT_BOLD=700

set void StyleSetWeight=2063(int style, int weight)
get int StyleGetWeight=2064(int style,)

In a language such as C# or Java it would be natural to code generate an enum called FontWeight and then have the methods take that as a parameter or return it rather than using an int.

ie

set void StyleSetWeight=2063(int style, FontWeight weight)
get FontWeight StyleGetWeight=2064(int style,)

then when calling the Scintilla api, the enum should be converted to an int.

But doing this kind of code generation with the format in its present form is impossible, as it is impossible to link the "int" to the "FontWeight".

[Neil Hodgson]

Adding type names in the indicated way is likely to cause externally maintained readers of the iface file format to break. Adding new feature lines will be safer, possibly something like
use FontWeight StyleSetWeight, StyleGetWeight
Thought will be needed on how to make this cover all cases while being unambiguous.

There are different ways that the term 'enumeration' is used with Scintilla using it just as a set of related constants. The style weight value can be any integer between 1 and 999, not just one of the values that start with SC_WEIGHT_.
http://www.scintilla.org/ScintillaDoc.html#SCI_STYLESETWEIGHT

Due to vacations and schedules I may not look at this for around 3 months.

[Kasper B. Graversen]

Hi Neil

Thanks for you reply. Since your writing I have had more experience with writing plugins. Here is a list of observations and recommendations for improvements.

1. The idea of a language independent "iface" file is a great idea! It really helps autogenerating a lot of boilercode. The format is a bit archaic - but since a parser has been provided, its not a big deal. And if I need to generate a type with 999 entries, I'd rather do that than expose an int that has a much larger range. And it compiles down to an int (in the case of C#) so there is no overhead. But the information needs be in the format for "plugin frameworks" to have a living chance of generating them.

2. The documentation of the "iface" file is in a sad state of affairs, you NEED to really understand intricate details that are explained on http://www.scintilla.org/ScintillaDoc.html . It holds all kinds of wonderful information- one example being the styleweight. Another being eg the SCI_GETSELECTIONSTART
   SCI_GETSELECTIONEND which behaves very differently to the anchor/current possition. It is to a point that the IDE that shows me the documentation from the "iface" file is irrelevant. The documentation and the "iface" documentation should be idential. This will mean a great boost of productivity as I can read the documentation in my IDE.

3. The api of scintialla is VAST! To the point that it needs be broken up. You have already done so in the documentation - so why not do the same for the "iface" file. Some sort of group that groups functions together. The grouping will serve two purposes

4. Serves as a placeholder for general documentation on a given "topic" that relates to a number of functions - eg. like the documentation generally relating to selections.
5. Serve as a means to generate navigation into the scintilla api. Rather than having only an entity "scintilla" with hundreds of different methods, it would be a nicer programming experience if plugin writers can do like "scintilla.SelectionAndInformation.SCI_GETSELECTIONMODE"

I do not thins necesarrily the existing underlying calling mechanics as they are today needs be changes, and perhaps the groups already established in the documenation is adequate. Can a function then live in more than one group? Sure why not if it makes sense. I'd rather see that than having one big pile of unrelated functions in one group just because they could be part of many groups.

Clearly as you highlight this will entain non-trivial changes. I thus want to suggest taking a different route: Create a new and improved file (with a new format, that naturally support nesting and preferably light-weight. Maybe json).
* From this file the webpage documentation should be generated,
* As should the current "iface" file. The "iface" file will be a reduced version of the new format - it will be there solely for backward compatibility.

Then at some point the "iface" file can be phased out.

This will allow you to do major overhaul without being constrained to the thinking of the old format and existing users of the "iface" file will benefit from much more elaborate documentation.

Comments are welcommed. - and I'd gladly assist in the process if you like my ideas.

.

[Neil Hodgson]

2 The documentation of the "iface" file is in a sad state of affairs, you NEED to really understand intricate details

The single lines give some context without bogging down in details.

3 To the point that it needs be broken up. You have already done so in the documentation - so why not do the same for the "iface" file.

The divisions in the documentation aren't great either. Some sections overlap and some APIs need to be discussed in multiple places. Finding a great Linnaean taxonomy here would be a huge job.

5 like "scintilla.SelectionAndInformation.SCI_GETSELECTIONMODE"

That is far too long and the second ID is just categorisation. Categorisation isn't that important compared with structural grouping.

All this sounds like too much effort. There are better things to spend very limited resources on.

[Thorsten Kani]

Not sure i i got all the details right... But seems to boil down to some simple question:
did one trained his mind on thin and fast c convention style.
or is another ones fav more the object.method related style.
Whatevers chosen .. each style has its advances and benefits.
But implementing more structure on external interfaces.. sounds at least reasonable to me.

[Neil Hodgson]

A structural (or Document Object Model) API would present something like Scintilla.Document and Scintilla.Styles[index] sub-objects that would then have methods and properties. That would be more useful than categorisation like "scintilla.SelectionAndInformation.SCI_GETSELECTIONMODE".

Its also more work: designing a sensible DOM, finding a way to express that model in an .iface file, and implementing the model in a way that can be easily accessed.

[Thorsten Kani]

hm.. im quite new on api design.. but if you have payload to do, i would love to see that one live.

[Zufu Liu]

Type info was added in https://sourceforge.net/p/scintilla/feature-requests/1297/