Plugin documentation - generated manual

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Plugin documentation - generated manual

Maurizio M. Gavioli
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
Reply | Threaded
Open this post in threaded view
|

Re: Plugin documentation - generated manual

lasconic
Administrator
All good for me. Werner?

2015-04-13 13:36 GMT+02:00 Maurizio M. Gavioli <[hidden email]>:
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/mscore-developer


------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/mscore-developer
Reply | Threaded
Open this post in threaded view
|

Re: Plugin documentation - generated manual

wschweer9
I am OK with all this and have some additions:
    - for every function/property enum a regression test is needed.
      Currently some functions/properties do not work.
    - changing anything in the score has to use the undo stack
    - it should not be possible to crash MuseScore with an script
    - enums for the scripting interface must be separated from c++ enums.
      After some experimenting with the current strategy of moving enums into a
      QObject derived class i came the the conclusion that this does not work. First the separate namespaces for
      enums do not work in JS. Second we loose the ability to forward declare enums
     in c++.
   - access to c++ implementation details should be removed
   - the scripting interface should be minimal, its not the goal (nor possible)
     to export more or less all the current c++ classes

Am 13.04.2015 um 13:48 schrieb Lasconic:
All good for me. Werner?

2015-04-13 13:36 GMT+02:00 Maurizio M. Gavioli <[hidden email]>:
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/mscore-developer



------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/mscore-developer


------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/mscore-developer
Reply | Threaded
Open this post in threaded view
|

Re: Plugin documentation - generated manual

Maurizio M. Gavioli
Werner Schweer wrote
I am OK with all this
OK
and have some additions:
My current concern is about documentation and, in particular, what can be fixed simply by working on comments.

Making the scripting framework more robust, reasonably complete on one hand and simpler on the other hand, as well as resolving conundrums in the C++/plug-in integration is an ampler goal. It is surely needed, but I would leave it for a second step.
     - for every function/property enum a regression test is needed. Currently some functions/properties do not work.
     - changing anything in the score has to use the undo stack
     - it should not be possible to crash MuseScore with an script
OK
     - enums for the scripting interface must be separated from c++ enums. After some experimenting with the current strategy of moving enums into a QObject derived class i came the the conclusion that this does not work. First the separate namespaces for enums do not work in JS. Second we loose the ability to forward declare enums in c++.
Is there a solution to this beyond duplicating all the enums in a form suitable for C++ and one suitable for the scripting framework?
    - access to c++ implementation details should be removed
    - the scripting interface should be minimal, its not the goal (nor possible) to export more or less all the current c++ classes
I think deciding what should be there and what shouldn't is not a clear cut decision to make; any guide line?

Thanks,

Maurizio