[Development] QDoc can't ignore Q_PROPERTY

[Andre Somers]

Op 9-3-2012 23:22, casper.vandonderen at nokia.com schreef:
> Just to make sure everybody understands:
> With this change applied all NOTIFY properties that are currently documented will not be documented anymore.
>
> If there are no objections before coming Tuesday (13 March) 09:00 Oslo time I will put this patch in.
I doubt if it is a good idea. Signals are often used outside the context 
of properties. I'm already not all that enthousiastic about not having 
the getters and the setters documented explicitly*, and now people will 
have to start looking at several places in the documentation to find out 
what signals there are too. I don't find that an improvement. I think it 
is great to mention in the property documentation that there is a notify 
signal and what that signal is and if that can be done automatically 
than all the better, but please _don't_ make that the only documentation.

André

*) It makes me search at more than one place in the class documentation 
for the available settings, as it is a bit arbitrary what is considered 
a property and what is not. I think there are even cases where a pair of 
getters & setters is only _documented_ as a property, but it is not 
defined as a Q_PROPERTY so anyone trying to use them using the 
properties API is at a loss at why that does not work...
>
>
> Casper
> ________________________________________
> From: Ramsay Lincoln (Nokia-MP/Brisbane)
> Sent: Friday, March 09, 2012 12:37 AM
> To: Vandonderen Casper (Nokia-MP/Oslo)
> Cc: ext Girish Ramakrishnan; development at qt-project.org
> Subject: Re: [Development] QDoc can't ignore Q_PROPERTY
>
> On 03/08/2012 07:38 PM, Vandonderen Casper (Nokia-MP/Oslo) wrote:
>> It might be that this was indeed an oversight.
>>
>> Can you create a bug report and assign it to me (I am not promising I have
>> time to fix it now, or you can fix qdoc yourself and add me as reviewer
>> ;-) )
> Ok... The "fix" is (as far as I can tell) a single line of code. With
> that in place, NOTIFY signals are handled the same as getters and
> setters for properties. Perhaps most significantly, documentation for
> the signal is silently ignored by qdoc.
>
> While trying to find that line, I found two other bits of code dealing
> with getters and setters but not notifiers. I've updated them too but I
> don't actually know what they do.
>
> http://codereview.qt-project.org/#change,19374
>
> --
> Lincoln Ramsay - Senior Software Engineer
> Qt Development Frameworks, Nokia - http://qt.nokia.com/
> _______________________________________________
> Development mailing list
> Development at qt-project.org
> http://lists.qt-project.org/mailman/listinfo/development