[Development] QDoc can't ignore Q_PROPERTY
andre at familiesomers.nl
Sat Mar 10 10:32:41 CET 2012
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.
*) 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...
> 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.
> Lincoln Ramsay - Senior Software Engineer
> Qt Development Frameworks, Nokia - http://qt.nokia.com/
> Development mailing list
> Development at qt-project.org
More information about the Development