Doc

2 files changed, 150 insertions, 13 deletions

diff --git a/src/declarative/qml/qdeclarativelist.cpp b/src/declarative/qml/qdeclarativelist.cpp
index af720d7..9691f32 100644
--- a/src/declarative/qml/qdeclarativelist.cpp
+++ b/src/declarative/qml/qdeclarativelist.cpp
@@ -85,18 +85,57 @@ void QDeclarativeListReferencePrivate::release()
         delete this;
 }
 
+/*!
+\class QDeclarativeListReference
+\brief The QDeclarativeListReference class allows the manipulation of QDeclarativeListProperty properties.
+
+QDeclarativeListReference allows programs to read from, and assign values to a QML list property in a 
+simple and type safe way.  A QDeclarativeListReference can be created by passing an object and property
+name or through a QDeclarativeProperty instance.  These two are equivalant:
+
+\code
+QDeclarativeListReference ref1(object, "children");
+
+QDeclarativeProperty ref2(object, "children");
+QDeclarativeListReference ref2 = qvariant_cast<QDeclarativeListReference>(ref2.read());
+\endcode
+
+Not all QML list properties support all operations.  A set of methods, canAppend(), canAt(), canClear() and
+canCount() allow programs to query whether an operation is supported on a given property.
+
+QML list properties are typesafe.  Only QObject's that derive from the correct base class can be assigned to
+the list.  The listElementType() method can be used to query the QMetaObject of the QObject type supported.
+Attempting to add objects of the incorrect type to a list property will fail.
+
+Like with normal lists, when accessing a list element by index, it is the callers responsibility to ensure 
+that it does not request an out of range element using the count() method before calling at().
+*/
+
+/*!
+Constructs an invalid instance.
+*/
 QDeclarativeListReference::QDeclarativeListReference()
 : d(0)
 {
 }
 
-QDeclarativeListReference::QDeclarativeListReference(QObject *o, const char *property, QDeclarativeEngine *engine)
+/*!
+Constructs a QDeclarativeListReference for \a object's \a property.  If \a property is not a list
+property, an invalid QDeclarativeListReference is created.  If \a object is destroyed after 
+the reference is constructed, it will automatically become invalid.  That is, it is safe to hold
+QDeclarativeListReference instances even after \a object is deleted.
+
+Passing \a engine is required to access some QML created list properties.  If in doubt, and an engine
+is available, pass it.
+*/
+QDeclarativeListReference::QDeclarativeListReference(QObject *object, const char *property, QDeclarativeEngine *engine)
 : d(0)
 {
-    if (!o || !property) return;
+    if (!object || !property) return;
 
     QDeclarativePropertyCache::Data local;
-    QDeclarativePropertyCache::Data *data = QDeclarativePropertyCache::property(engine, o, QLatin1String(property), local);
+    QDeclarativePropertyCache::Data *data = 
+        QDeclarativePropertyCache::property(engine, object, QLatin1String(property), local);
 
     if (!data || !(data->flags & QDeclarativePropertyCache::Data::IsQList)) return;
 
@@ -106,20 +145,22 @@ QDeclarativeListReference::QDeclarativeListReference(QObject *o, const char *pro
     if (listType == -1) return;
 
     d = new QDeclarativeListReferencePrivate;
-    d->object = o;
+    d->object = object;
     d->elementType = p?p->rawMetaObjectForType(listType):QDeclarativeMetaType::qmlType(listType)->baseMetaObject();
     d->propertyType = data->propType;
 
     void *args[] = { &d->property, 0 };
-    QMetaObject::metacall(o, QMetaObject::ReadProperty, data->coreIndex, args);
+    QMetaObject::metacall(object, QMetaObject::ReadProperty, data->coreIndex, args);
 }
 
+/*! \internal */
 QDeclarativeListReference::QDeclarativeListReference(const QDeclarativeListReference &o)
 : d(o.d)
 {
     if (d) d->addref();
 }
 
+/*! \internal */
 QDeclarativeListReference &QDeclarativeListReference::operator=(const QDeclarativeListReference &o)
 {
     if (o.d) o.d->addref();
@@ -128,60 +169,108 @@ QDeclarativeListReference &QDeclarativeListReference::operator=(const QDeclarati
     return *this;
 }
 
+/*! \internal */
 QDeclarativeListReference::~QDeclarativeListReference()
 {
     if (d) d->release();
 }
 
+/*!
+Returns true if the instance refers to a valid list property, otherwise false.
+*/
 bool QDeclarativeListReference::isValid() const
 {
     return d && d->object;
 }
 
+/*!
+Returns the list property's object.  Returns 0 if the reference is invalid.
+*/
 QObject *QDeclarativeListReference::object() const
 {
     if (isValid()) return d->object;
     else return 0;
 }
 
+/*!
+Returns the QMetaObject for the elements stored in the list property.  Returns 0 if the reference
+is invalid.
+
+The QMetaObject can be used ahead of time to determine whether a given instance can be added
+to a list.
+*/
 const QMetaObject *QDeclarativeListReference::listElementType() const
 {
     if (isValid()) return d->elementType;
     else return 0;
 }
 
+/*!
+Returns true if the list property can be appended to, otherwise false.  Returns false if the
+reference is invalid.
+
+\sa append()
+*/
 bool QDeclarativeListReference::canAppend() const
 {
     return (isValid() && d->property.append);
 }
 
+/*!
+Returns true if the list property can queried by index, otherwise false.  Returns false if the
+reference is invalid.
+
+\sa at()
+*/
 bool QDeclarativeListReference::canAt() const
 {
     return (isValid() && d->property.at);
 }
 
+/*!
+Returns true if the list property can be cleared, otherwise false.  Returns false if the
+reference is invalid.
+
+\sa clear()
+*/
 bool QDeclarativeListReference::canClear() const
 {
     return (isValid() && d->property.clear);
 }
 
+/*!
+Returns true if the list property can be queried for its element count, otherwise false.  
+Returns false if the reference is invalid.
+
+\sa count()
+*/
 bool QDeclarativeListReference::canCount() const
 {
     return (isValid() && d->property.count);
 }
 
-bool QDeclarativeListReference::append(QObject *o) const
+/*!
+Appends \a object to the list.  Returns true if the operation succeeded, otherwise false.
+
+\sa canAppend()
+*/
+bool QDeclarativeListReference::append(QObject *object) const
 {
     if (!canAppend()) return false;
 
-    if (o && !QDeclarativePropertyPrivate::canConvert(o->metaObject(), d->elementType))
+    if (object && !QDeclarativePropertyPrivate::canConvert(object->metaObject(), d->elementType))
         return false;
 
-    d->property.append(&d->property, o);
+    d->property.append(&d->property, object);
 
     return true;
 }
 
+/*!
+Returns the list element at \a index, or 0 if the operation failed.
+
+\sa canAt()
+*/
 QObject *QDeclarativeListReference::at(int index) const
 {
     if (!canAt()) return 0;
@@ -189,6 +278,11 @@ QObject *QDeclarativeListReference::at(int index) const
     return d->property.at(&d->property, index);
 }
 
+/*!
+Clears the list.  Returns true if the operation succeeded, otherwise false.
+
+\sa canClear()
+*/
 bool QDeclarativeListReference::clear() const
 {
     if (!canClear()) return false;
@@ -198,6 +292,9 @@ bool QDeclarativeListReference::clear() const
     return true;
 }
 
+/*!
+Returns the number of objects in the list, or 0 if the operation failed.
+*/
 int QDeclarativeListReference::count() const
 {
     if (!canCount()) return 0;
diff --git a/src/declarative/qml/qdeclarativeproperty.cpp b/src/declarative/qml/qdeclarativeproperty.cpp
index 9ed760e..e1ec2cd 100644
--- a/src/declarative/qml/qdeclarativeproperty.cpp
+++ b/src/declarative/qml/qdeclarativeproperty.cpp
@@ -311,10 +311,10 @@ QDeclarativeProperty::QDeclarativeProperty(const QDeclarativeProperty &other)
 
   This enum specifies a category of QML property.
 
-  \value InvalidCategory The property is invalid.
-  \value List The property is a QList pointer
+  \value InvalidCategory The property is invalid, or is a signal property.
+  \value List The property is a QDeclarativeListProperty list property
   \value Object The property is a QObject derived type pointer
-  \value Normal The property is none of the above.
+  \value Normal The property is a normal value property.
  */
 
 /*!
@@ -752,18 +752,39 @@ QVariant QDeclarativeProperty::read() const
     return QVariant();
 }
 
+/*!
+Return the \a name property value of \a object.  This method is equivalent to:
+\code
+    QDeclarativeProperty p(object, name);
+    p.read();
+\endcode
+*/
 QVariant QDeclarativeProperty::read(QObject *object, const QString &name)
 {
     QDeclarativeProperty p(object, name);
     return p.read();
 }
 
+/*!
+Return the \a name property value of \a object.  This method is equivalent to:
+\code
+    QDeclarativeProperty p(object, name, context);
+    p.read();
+\endcode
+*/
 QVariant QDeclarativeProperty::read(QObject *object, const QString &name, QDeclarativeContext *ctxt)
 {
     QDeclarativeProperty p(object, name, ctxt);
     return p.read();
 }
 
+/*!
+Return the \a name property value of \a object.  This method is equivalent to:
+\code
+    QDeclarativeProperty p(object, name, engine);
+    p.read();
+\endcode
+*/
 QVariant QDeclarativeProperty::read(QObject *object, const QString &name, QDeclarativeEngine *engine)
 {
     QDeclarativeProperty p(object, name, engine);
@@ -802,9 +823,7 @@ QVariant QDeclarativePropertyPrivate::readValueProperty()
     }
 }
 
-//###
 //writeEnumProperty MIRRORS the relelvant bit of QMetaProperty::write AND MUST BE KEPT IN SYNC!
-//###
 bool QDeclarativePropertyPrivate::writeEnumProperty(const QMetaProperty &prop, int idx, QObject *object, const QVariant &value, int flags)
 {
     if (!object || !prop.isWritable())
@@ -1054,12 +1073,26 @@ bool QDeclarativeProperty::write(const QVariant &value) const
     return QDeclarativePropertyPrivate::write(*this, value, 0);
 }
 
+/*!
+Writes \a value to the \a name property of \a object.  This method is equivalent to:
+\code
+    QDeclarativeProperty p(object, name);
+    p.write(value);
+\endcode
+*/
 bool QDeclarativeProperty::write(QObject *object, const QString &name, const QVariant &value)
 {
     QDeclarativeProperty p(object, name);
     return p.write(value);
 }
 
+/*!
+Writes \a value to the \a name property of \a object.  This method is equivalent to:
+\code
+    QDeclarativeProperty p(object, name, ctxt);
+    p.write(value);
+\endcode
+*/
 bool QDeclarativeProperty::write(QObject *object, const QString &name, const QVariant &value, 
                                  QDeclarativeContext *ctxt)
 {
@@ -1067,6 +1100,13 @@ bool QDeclarativeProperty::write(QObject *object, const QString &name, const QVa
     return p.write(value);
 }
 
+/*!
+Writes \a value to the \a name property of \a object.  This method is equivalent to:
+\code
+    QDeclarativeProperty p(object, name, engine);
+    p.write(value);
+\endcode
+*/
 bool QDeclarativeProperty::write(QObject *object, const QString &name, const QVariant &value, 
                                  QDeclarativeEngine *engine)
 {