Doxyqml, supporting type

[Aleix Pol]

On Mon, Oct 22, 2012 at 5:12 PM, Aurélien Gâteau <agateau at kde.org> wrote:
> Hi,
>
> I have been working a bit more on Doxyqml, the Doxygen input filter for QML
> [1]. It now uses a more robust parser, is growing a test-suite and can
> override types when needed, allowing you to specify types for function
> parameters, return values and properties.
>
> Here is an excerpt of the README:
>
> -----------------------------
> ## Functions
>
> Functions in QML are untyped, but you can define types in the documentation
> like this:
>
>     /**
>      * Create a user
>      * @param type:string firstname User firstname
>      * @param type:string lastname User lastname
>      * @param type:int User age
>      * @return type:User The User object
>      */
>     function createUser(firstname, lastname, age);
>
> ## Properties
>
> QML properties are typed, doxyqml will take advantage of the existing type.
> You can nevertheless overwrite the type using the same `type:<name>` syntax.
> This is useful for example to document property aliases:
>
>     /** type:string The user lastname */
>     property alias lastname: someObject.text
>
> ## Signals
>
> QML signals are typed, so there is no need to use the `type:<name>` syntax to
> document their parameters. Using `type:<name>` syntax in signal documentation
> will not work: Doxyqml won't strip it out and Doxygen will confuse it with the
> parameter name.
>
>     /**
>      * User just logged in
>      * @param user The user which logged in
>      */
>     signal loggedIn(User user)
> -----------------------------
>
> I decided to use a syntax of the form `type:<name>` because it makes it
> possible to skip type definition. This is handy for properties, since they
> already have type information so specifying a type is not mandatory for them.
>
> I am wondering however if it would be better to simplify the syntax for
> functions so that @param and @return expect the first argument to always be a
> type, making it possible to write:
>
>     @param string lastname User lastname
>
> instead of:
>
>     @param type:string lastname User lastname
>
> The plus of this solution is that it is a bit shorter to type (no "type:"
> prefix), the minus being that the syntax is a bit inconsistent with properties
> documentation (which would still require the "type:" prefix, because type has
> to be optional there)
>
> What do you think?
>
> Aurélien
>
> [1]: Available from kde:scratch/gateau/doxyqml
> _______________________________________________
> Plasma-devel mailing list
> Plasma-devel at kde.org
> https://mail.kde.org/mailman/listinfo/plasma-devel

I think you are great Aurélien :D

More seriously though, I think that a patch on some current code would
be really helpful.

Also did we consider how different will be C++ components vs. QML
components? Ideally they should have a similar aspect since we'll
likely be using them both together.

Code-wise, I don't think having a type: prefix is bad and given that
the type can be any class name, it can be good to have it specified
because it's easy to read it, if it starts with string but not so easy
if it starts with e.g. TextField.

Aleix