From 2f91cbaccb532f5e0b2e7146e6184617aee25358 Mon Sep 17 00:00:00 2001 From: Topi Reinio Date: Wed, 21 Oct 2020 00:34:40 +0200 Subject: Doc: Fix documentation warnings for QProperty and related classes Task-number: QTBUG-86295 Change-Id: I547f4cf34d9721f56ba1cd665218f66597ffbb5c Reviewed-by: Lars Knoll --- src/corelib/kernel/qproperty.cpp | 171 ++++++++++----------------------------- 1 file changed, 43 insertions(+), 128 deletions(-) (limited to 'src/corelib/kernel/qproperty.cpp') diff --git a/src/corelib/kernel/qproperty.cpp b/src/corelib/kernel/qproperty.cpp index 3ef37528d5..e4f12500a3 100644 --- a/src/corelib/kernel/qproperty.cpp +++ b/src/corelib/kernel/qproperty.cpp @@ -655,27 +655,27 @@ QString QPropertyBindingError::description() const used with care, as updates to the values will not get propagated to any bindings that depend on this property. - You should usually call value() and setValue() on QProperty or QBindablePropertyData, not use + You should usually call value() and setValue() on QProperty or QObjectBindableProperty, not use the low level mechanisms provided in this class. */ -/*! \fn QPropertyData::parameter_type QPropertyData::valueBypassingBindings() const +/*! \fn template QPropertyData::parameter_type QPropertyData::valueBypassingBindings() const - \returns the data stored in this property. + Returns the data stored in this property. \note As this will bypass any binding evaluation it might return an outdated value if a binding is set on this property. Using this method will also not register the property access with any currently executing binding. */ -/*! \fn void QPropertyData::setValueBypassingBindings(parameter_type v) +/*! \fn template void QPropertyData::setValueBypassingBindings(parameter_type v) Sets the data value stored in this property to \a v. \note Using this method will bypass any potential binding registered for this property. */ -/*! \fn void QPropertyData::setValueBypassingBindings(rvalue_ref v) +/*! \fn template void QPropertyData::setValueBypassingBindings(rvalue_ref v) \overload Sets the data value stored in this property to \a v. @@ -809,36 +809,16 @@ QString QPropertyBindingError::description() const */ /*! - \fn template QProperty::operator T() const - - Returns the value of the property. This may evaluate a binding expression that - is tied to this property, before returning the value. -*/ - -/*! - \fn template void QProperty::setValue(const T &newValue) + \fn template void QProperty::setValue(rvalue_ref newValue) + \fn template void QProperty::setValue(parameter_type newValue) Assigns \a newValue to this property and removes the property's associated binding, if present. */ /*! - \fn template void QProperty::setValue(T &&newValue) - \overload - - Assigns \a newValue to this property and removes the property's associated - binding, if present. -*/ - -/*! - \fn template QProperty &QProperty::operator=(const T &newValue) - - Assigns \a newValue to this property and returns a reference to this QProperty. -*/ - -/*! - \fn template QProperty &QProperty::operator=(T &&newValue) - \overload + \fn template QProperty &QProperty::operator=(rvalue_ref newValue) + \fn template QProperty &QProperty::operator=(parameter_type newValue) Assigns \a newValue to this property and returns a reference to this QProperty. */ @@ -874,17 +854,6 @@ QString QPropertyBindingError::description() const the next time the value of this property is read. */ -/*! - \fn template QPropertyBinding QProperty::setBinding(QPropertyBinding &&newBinding) - \overload - - Associates the value of this property with the provided \a newBinding - expression and returns the previously associated binding. The first time the - property value is read, the binding is evaluated. Whenever a dependency of the - binding changes, the binding will be re-evaluated the next time the value of - this property is read. -*/ - /*! \fn template QPropertyBinding bool QProperty::setBinding(const QUntypedPropertyBinding &newBinding) \overload @@ -948,26 +917,26 @@ QString QPropertyBindingError::description() const */ /*! - \class QBindablePropertyData + \class QObjectBindableProperty \inmodule QtCore - \brief The QBindablePropertyData class is a template class that enables automatic property bindings + \brief The QObjectBindableProperty class is a template class that enables automatic property bindings for property data stored in QObject derived classes. \since 6.0 \ingroup tools - QBindablePropertyData is a generic container that holds an + QObjectBindableProperty is a generic container that holds an instance of T and behaves mostly like \l QProperty. The extra template parameters are used to identify the surrounding class and a member function of that class. The member function will be called whenever the value held by the property changes. - You can use QBindablePropertyData to add binding support to code that uses Q_PROPERTY. - The getter and setter methods are easy to adapt for accessing a \l QBindablePropertyData + You can use QObjectBindableProperty to add binding support to code that uses Q_PROPERTY. + The getter and setter methods are easy to adapt for accessing a \l QObjectBindableProperty rather than the plain value. In order to invoke the change signal on property changes, use - QBindablePropertyData and pass the change signal as a callback. + QObjectBindableProperty and pass the change signal as a callback. - QBindablePropertyData is usually not used directly, instead an instance of it is created by + QObjectBindableProperty is usually not used directly, instead an instance of it is created by using the Q_BINDABLE_PROPERTY_DATA macro. Use the Q_BINDABLE_PROPERTY macro in the class declaration to declare the property as bindable. @@ -976,44 +945,42 @@ QString QPropertyBindingError::description() const class MyClass : public QObject { \Q_OBJECT - Q_PROPERTY(int x READ x WRITE setX NOTIFY xChanged) + Q_PROPERTY(int x READ x WRITE setX NOTIFY xChanged BINDABLE bindableX) public: int x() const { return xProp; } void setX(int x) { xProp = x; } - // declare the property as bindable. The data needs to be stored in a QBindablePropertyData instance. - // The last argument of the macro tells moc how to access that instance. - Q_BINDABLE_PROPERTY(MyClass, x, x, xProp) + Bindable bindableX() { return QBindable(&xProp); } signals: void xChanged(); private: // Declare the instance of the bindable property data. - Q_BINDABLE_PROPERTY_DATA(MyClass, int, xProp, &MyClass::xChanged) + Q_OBJECT_BINDABLE_PROPERTY(MyClass, int, xProp, &MyClass::xChanged) }; \endcode */ /*! - \fn template QBindablePropertyData::QBindablePropertyData() + \fn template QObjectBindableProperty::QObjectBindableProperty() Constructs a property with a default constructed instance of T. */ /*! - \fn template explicit QBindablePropertyData::QBindablePropertyData(const T &initialValue) + \fn template explicit QObjectBindableProperty::QObjectBindableProperty(const T &initialValue) Constructs a property with the provided \a initialValue. */ /*! - \fn template explicit QBindablePropertyData::QBindablePropertyData(T &&initialValue) + \fn template explicit QObjectBindableProperty::QObjectBindableProperty(T &&initialValue) Move-Constructs a property with the provided \a initialValue. */ /*! - \fn template QBindablePropertyData::QBindablePropertyData(Class *owner, const QPropertyBinding &binding) + \fn template QObjectBindableProperty::QObjectBindableProperty(Class *owner, const QPropertyBinding &binding) Constructs a property that is tied to the provided \a binding expression. The first time the property value is read, the binding is evaluated. Whenever a @@ -1023,7 +990,7 @@ QString QPropertyBindingError::description() const */ /*! - \fn template QBindablePropertyData::QBindablePropertyData(Class *owner, QPropertyBinding &&binding) + \fn template QObjectBindableProperty::QObjectBindableProperty(Class *owner, QPropertyBinding &&binding) Constructs a property that is tied to the provided \a binding expression. The first time the property value is read, the binding is evaluated. Whenever a @@ -1034,37 +1001,30 @@ QString QPropertyBindingError::description() const /*! - \fn template template QBindablePropertyData::QBindablePropertyData(Class *owner, Functor &&f) + \fn template template QObjectBindableProperty::QObjectBindableProperty(Functor &&f) Constructs a property that is tied to the provided binding expression \a f. The first time the property value is read, the binding is evaluated. Whenever a dependency of the binding changes, the binding will be re-evaluated the next - time the value of this property is read. When the property value changes \a - owner is notified via the Callback function. + time the value of this property is read. */ /*! - \fn template QBindablePropertyData::~QBindablePropertyData() + \fn template QObjectBindableProperty::~QObjectBindableProperty() Destroys the property. */ /*! - \fn template T QBindablePropertyData::value() const + \fn template T QObjectBindableProperty::value() const Returns the value of the property. This may evaluate a binding expression that is tied to this property, before returning the value. */ /*! - \fn template QBindablePropertyData::operator T() const - - Returns the value of the property. This may evaluate a binding expression that - is tied to this property, before returning the value. -*/ - -/*! - \fn template void QBindablePropertyData::setValue(Class *owner, const T &newValue) + \fn template void QObjectBindableProperty::setValue(parameter_type newValue) + \fn template void QObjectBindableProperty::setValue(rvalue_ref newValue) Assigns \a newValue to this property and removes the property's associated binding, if present. If the property value changes as a result, calls the @@ -1072,16 +1032,7 @@ QString QPropertyBindingError::description() const */ /*! - \fn template void QBindablePropertyData::setValue(Class *owner, T &&newValue) - \overload - - Assigns \a newValue to this property and removes the property's associated - binding, if present. If the property value changes as a result, calls the - Callback function on \a owner. -*/ - -/*! - \fn template QPropertyBinding QBindablePropertyData::setBinding(Class *owner, const QPropertyBinding &newBinding) + \fn template QPropertyBinding QObjectBindableProperty::setBinding(const QPropertyBinding &newBinding) Associates the value of this property with the provided \a newBinding expression and returns the previously associated binding. The first time the @@ -1092,7 +1043,7 @@ QString QPropertyBindingError::description() const */ /*! - \fn template template QPropertyBinding QBindablePropertyData::setBinding(Class *owner, Functor f) + \fn template template QPropertyBinding QObjectBindableProperty::setBinding(Functor f) \overload Associates the value of this property with the provided functor \a f and @@ -1104,40 +1055,27 @@ QString QPropertyBindingError::description() const */ /*! - \fn template QPropertyBinding QBindablePropertyData::setBinding(Class *owner, QPropertyBinding &&newBinding) - \overload - - Associates the value of this property with the provided \a newBinding - expression and returns the previously associated binding. The first time the - property value is read, the binding is evaluated. Whenever a dependency of the - binding changes, the binding will be re-evaluated the next time the value of - this property is read. When the property value changes \a owner is notified - via the Callback function. -*/ - -/*! - \fn template QPropertyBinding bool QBindablePropertyData::setBinding(Class *owner, const QUntypedPropertyBinding &newBinding) + \fn template QPropertyBinding bool QObjectBindableProperty::setBinding(const QUntypedPropertyBinding &newBinding) \overload Associates the value of this property with the provided \a newBinding expression. The first time the property value is read, the binding is evaluated. Whenever a dependency of the binding changes, the binding will be re-evaluated - the next time the value of this property is read. When the property value - changes \a owner is notified via the Callback function. + the next time the value of this property is read. - Returns true if the type of this property is the same as the type the binding - function returns; false otherwise. + Returns \c true if the type of this property is the same as the type the binding + function returns; \c false otherwise. */ /*! - \fn template bool QBindablePropertyData::hasBinding() const + \fn template bool QObjectBindableProperty::hasBinding() const Returns true if the property is associated with a binding; false otherwise. */ /*! - \fn template QPropertyBinding QBindablePropertyData::binding() const + \fn template QPropertyBinding QObjectBindableProperty::binding() const Returns the binding expression that is associated with this property. A default constructed QPropertyBinding will be returned if no such @@ -1145,7 +1083,7 @@ QString QPropertyBindingError::description() const */ /*! - \fn template QPropertyBinding QBindablePropertyData::takeBinding() + \fn template QPropertyBinding QObjectBindableProperty::takeBinding() Disassociates the binding expression from this property and returns it. After calling this function, the value of the property will only change if you @@ -1153,7 +1091,7 @@ QString QPropertyBindingError::description() const */ /*! - \fn template template QPropertyChangeHandler QBindablePropertyData::onValueChanged(Functor f) + \fn template template QPropertyChangeHandler QObjectBindableProperty::onValueChanged(Functor f) Registers the given functor \a f as a callback that shall be called whenever the value of the property changes. @@ -1167,7 +1105,7 @@ QString QPropertyBindingError::description() const */ /*! - \fn template template QPropertyChangeHandler QBindablePropertyData::subscribe(Functor f) + \fn template template QPropertyChangeHandler QObjectBindableProperty::subscribe(Functor f) Subscribes the given functor \a f as a callback that is called immediately and whenever the value of the property changes in the future. @@ -1181,7 +1119,7 @@ QString QPropertyBindingError::description() const */ /*! - \fn template QtPrivate::QPropertyBase &QBindablePropertyData::propertyBase() const + \fn template QtPrivate::QPropertyBase &QObjectBindableProperty::propertyBase() const \internal */ @@ -1272,14 +1210,6 @@ QString QPropertyBindingError::description() const associated binding, if present. */ -/*! - \fn template void QPropertyAlias::setValue(T &&newValue) - \overload - - Assigns \a newValue to the aliased property and removes the property's - associated binding, if present. -*/ - /*! \fn template QPropertyAlias &QPropertyAlias::operator=(const T &newValue) @@ -1320,21 +1250,6 @@ QString QPropertyBindingError::description() const default-constructed QPropertyBinding. */ -/*! - \fn template QPropertyBinding QPropertyAlias::setBinding(QPropertyBinding &&newBinding) - \overload - - Associates the value of the aliased property with the provided \a newBinding - expression and returns any previous binding the associated with the aliased - property. The first time the property value is read, either from the property - itself or from any alias, the binding is evaluated. Whenever a dependency of - the binding changes, the binding will be re-evaluated the next time the value - of this property is read. - - Returns any previous binding associated with the property, or a - default-constructed QPropertyBinding. -*/ - /*! \fn template QPropertyBinding bool QPropertyAlias::setBinding(const QUntypedPropertyBinding &newBinding) \overload @@ -1350,7 +1265,7 @@ QString QPropertyBindingError::description() const */ /*! - \fn template template QPropertyBinding setBinding(Functor f) + \fn template template QPropertyBinding QPropertyAlias::setBinding(Functor f) \overload Associates the value of the aliased property with the provided functor \a f -- cgit v1.2.3