Changing parameter names in Scintilla.iface

[Neil Hodgson]

There are many minor differences between the interface file in Scintilla.iface and the documentation in ScintillaDoc.html. I’d like to harmonise these two files which will make reading more consistent and also allows for some automated checking and other tools such as extracting united information into other forms.

One difference is parameter names: one has “mask” and the other “eventMask” or “milliseconds” versus “periodMilliseconds”. I’d like to choose either one or the other or something better in each case. This may cause problems in downstream projects if the parameter names are being used, for example in a call like scintilla.SetModEventMask(mask=INSERTCHECK). Most languages have only positional parameters but others allow or prefer named parameters.

So, object if this type of change will be difficult for you.
*************************************************************

The set of types used in the documentation may be expanded to include some of those used in Scintilla.iface like “colour” or “position" instead of “int”.

Adding return types to the documentation may be worthwhile, possibly looking like “SCI_GETLEXER → int”.

A bug found while examining this is that Scintilla.iface has
get int GetPropertyInt=4010(string key,)
but the documentation shows an additional parameter
SCI_GETPROPERTYINT(const char *key, int default)

Neil

[Neil Hodgson]

Attached is the current patch set for harmonizing parameter names between Scintilla.iface and ScintillaDoc.html. It also adds a CSS class ‘parameter’ to mark explanations of API parameters which are then styled as italics.

Neil

[Greg Smith]

   A bug found while examining this is that Scintilla.iface has
get int GetPropertyInt=4010(string key,)
   but the documentation shows an additional parameter
SCI_GETPROPERTYINT(const char *key, int default)

 Yes, I had implemented this call without the second argument, which would result in a 0 for every missing property... Thanks for the heads up.

[Neil Hodgson]

A version of the documentation with return types is available from
http://www.scintilla.org/ScintillaDox.html

The return types were added by a script which may not be completely correct.

Some types should be tweaked: "SCI_CREATEDOCUMENT → int” could be "SCI_CREATEDOCUMENT → document”.

Neil

[Neil Hodgson]

Committed changes to documentation and interface file.
https://sourceforge.net/p/scintilla/code/ci/951b7822bb3aa8d8b9d04b91624ed3be1d079a45/

This is a very large change set so there is a good chance I have made some mistakes.

Neil