[Development] [Feature] Q_INFO: Annotations for classes, methods, properties and enums

[Olivier Goffart]

Hi,

On Sunday 01 September 2013 13:20:10 Stefan Merettig wrote:
> The meta object compiler currently supports something it calls 'method
> tags', where it collects identifiers it doesn't know in front of
> methods:
> 
>     #ifndef Q_MOC_RUN
>     # define MYTAG
>     #endif
>     ...
>     MYTAG void myFunction ();
> 
> While this feature is already helpful for simple scenarios, it is quite
> limited as it doesn't support arguments at all (It throws a syntax
> error if a user tries to do this).
> 
> To overcome this I'd like to add a macro called Q_INFO (As proposed by
> Richard):
> 
>     #define Q_INFO(...)


I think adding general information to method or properties are a good idea.
The current tag system is indeed very limited.
But before trying to get something to general, we need to focus on use cases.

 
> It is up to debate what structure the argument should have. The
> following
> ideas were proposed:
>     1) Q_INFO("myTag" LIST "foo" "bar" END)
>     2) Q_INFO("myTag" ARGS "foo", "bar") // Or ARGUMENTS instead of ARGS
>     3) Q_INFO(myTag ("foo", "bar")) // Alternative: The name is "quoted"

I add my ideas:

 Q_INFO(key = value) 
 Q_INFO(key, value)
 Q_INFO("key", "value")

I rather opt for a key/value system.  then it can easily be queried with 
something like.
QByteArray QMetaMethod::methodInfo(const char *key);

What is really your use case with several argument that cannot be done with a 
key/value system?  Worst case you can do something like
 Q_INFO(key.arg1 = foo)
 Q_INFO(key.arg2 = bar)


> Q_INFO can be prefixed to ...
> 1) Classes

We already have Q_CLASS_INFO for classes.

> 2) Methods (Signals, slots, Q_INVOKABLE methods)

Make sens.

> 3) Properties

For propeties, i'd rather see something within the property.
For example
 Q_PROPERTY(foo MEMBER m_foo  INFO key=value)


> 4) Enums which are exported through Q_ENUMS()
>     Note: The Q_INFO macro is prefixed to the enum itself in this case!

> WHY as in USE-CASE EXAMPLE
> 
> Pretend you have a library which provides a RPC server with a user
> management component. You write a QObject class which shall implement
> all slots  you want to expose. Not every user should be able to invoke
> every slot, thus you use the annotation mechanism which lets you define
> the desired behaviour right there, in the header.
> 
>     Q_INFO("Awesome.RpcServer.path" ARGS "services/stuff")
>     class MyServices : public QObject {
>       Q_INFO("Awesome.RpcServer.isPublic" ARGS "false")
>       Q_PROPERTY(int activeUserCount READ activeUserCount)
>       ...
>       public slots:
>       Q_INFO("Awesome.RpcServer.requiredPermissions" ARGS "admin")
>       Q_INFO("Awesome.RpcServer.onlyAuthenticatedUsers")
>       bool deleteUser (QString user);
>       ...
>     };

BTW,  All of that can be done currently by abusing Q_CLASSINFO

class MyServices : public QObject {
   Q_CLASSINFO("Awesome.RpcServer.Path", "false")
   Q_PROPERTY(int activeUserCount READ activeUserCount)
   Q_CLASSINFO("Awesome.RpcServer.isPublic.activeUserCount", "false")

 public slots:
       bool deleteUser (QString user);

   Q_CLASSINFO("Awesome.RpcServer.requiredPermissionssPublic.deleteUser",
                         "admin")
   Q_CLASSINFO("Awesome.RpcServer.onlyAuthenticatedUsers.deleteUser",
                         "true")
 
};

That said, it would indeed be better to have info class.


[...]
> NEEDED CHANGES
> 
> 1) The meta object compiler (moc) needs to be extended to support this
>     feature.

Yes.
Notice that we could also re-use the "tag" field of the data array for some 
purpose (it would mean the old tag or the info count depending on one of the 
bit or of the revision)

> 2) qglobal.h needs to be adjusted to carry #define Q_INFO(...)

qobjectdefs.h

> 3) At least another class needs to be introduced to Qt. I'd like to
>     call it QMetaInfo, though I'm fine with a different name if anyone
>     thinks that  this name is bad for some reason. Other QMeta* classes
>     need to be adjusted.

There is QMetaClassInfo,  but i'd rather see a key value API.

> On top of that some internal Qt classes need to be made aware of this
> feature. For a more complete list, please see the commit messages in
> the
> patch set.
> 
> TECHNOLOGY PREVIEW
> 
> Thiago mentioned that a modified moc would be helpful, so I worked on
> it. You can view the patch set here:
> https://codereview.qt-project.org/#change,64287
> 
> A moc with my modifications supports Q_INFO everywhere I'd like it to
> be available. No changes were made outside moc's tree though.

-- 
Olivier

Woboq - Qt services and support - http://woboq.com - http://code.woboq.org