A) Properties
Currently the plug-in documentation generated from comments in the source
code uses a C/Qt notation in properties:
*) MuseScore objects are prefixed with "Ms::" (like "Ms::Measure")
*) String returned values are labelled as "QString"
*) Returned pointers are notated as C pointers ("Ms::Element*")
*) Enum types are notated with C syntax ("Ms::Element::Placement") and their
values -- if at all given -- are unqualified ("ABOVE, BELOW")
This might be misleading for the user working in the JavaScript plug-in
environment, where strings are simply called "string", MS objects are named
with their unqualified type ("Measure" and not "Ms::"Measure" or
"Ms.Measure"), pointers are not indicated at all and enums use a different
syntax.
What about cleaning all the class headers contributing to the plug-in doc,
removing C/Qt specific terms, aligning them with the JS syntax and notating
the enums with the syntax actually used ("Element.Placement" as returned
type and, as enum values, "Element.ABOVE, Element.BELOW" or maybe
"Element.ABOVE, .BELOW" for short)?
Note: JS does not distinguish between int and double as separate types (both
are Number, I think). However, as this may be an easy to understand and
useful piece of info and there is rarely (if ever) need to name those types,
I propose to leave this distinction in the doc.
B) Methods
Simply relying on the "Q_INVOKABLE" keyword might be not enough: there might
be methods which is not the case to document (like the potentially obsolete
"Cursor.rewind()" or perhaps "Element.clone()").
I propose to ignore for the plug-in documentation functions with Q_INVOKABLE
keyword, but lacking a plug-in-specific //@" comment.
Thanks,
Maurizio
--
View this message in context:
http://dev-list.musescore.org/Plugin-documentation-generated-manual-tp7579164.html
Sent from the MuseScore Developer mailing list archive at Nabble.com.
------------------------------------------------------------------------------
BPM Camp - Free Virtual Workshop May 6th at 10am PDT/1PM EDT
Develop your own process in accordance with the BPMN 2 standard
Learn Process modeling best practices with Bonita BPM through live exercises
http://www.bonitasoft.com/be-part-of-it/events/bpm-camp-virtual- event?utm_
source=Sourceforge_BPM_Camp_5_6_15&utm_medium=email&utm_campaign=VA_SF
_______________________________________________
Mscore-developer mailing list
Mscore-developer@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/mscore-developer
