Doc: edit qmldesigner designercore model API docs

Do not use the \returns command as it does not exist.
Do not use the \arg command (use \a instead).
Do not use the \see command (use \sa instead).
Do not use the \name command (could use \ingroup, instead)
Remove \brief command from function descriptions for
consistency (as it is optional).
Fix punctuation, grammar, and style issues.
Remove obsolete documentation and fix function signatures.

Change-Id: I0bff8c00aefdcff451b2d1cefe8b99407bfb4222
Reviewed-by: Thomas Hartmann <Thomas.Hartmann@digia.com>

5 files changed, 88 insertions, 125 deletions

diff --git a/src/plugins/qmldesigner/designercore/model/abstractproperty.cpp b/src/plugins/qmldesigner/designercore/model/abstractproperty.cpp
index 67cc807d8d..267d01d716 100644
--- a/src/plugins/qmldesigner/designercore/model/abstractproperty.cpp
+++ b/src/plugins/qmldesigner/designercore/model/abstractproperty.cpp
@@ -120,10 +120,9 @@ AbstractView *AbstractProperty::view() const
 }
 
  /*!
- \brief AbstractProperty is a value holder for a property
- \return the value of the property
+ Holds a value for a property. Returns the value of the property.
 
- The QVariant is null if the property doesn't exists.
+ The QVariant is null if the property does not exist.
 */
 PropertyName AbstractProperty::name() const
 {
@@ -135,13 +134,13 @@ PropertyName AbstractProperty::name() const
 }
 
  /*!
- \brief Checks if the property is valid.
+ Checks if the property is valid.
 
- A prooperty is valid if the belonging ModelNode
+ A property is valid if the belonging model node
  is valid. This function is not overloaded for
  subclasses.
 
- \return the property is valid for true return value
+ Returns whether the property is valid for the \c true return value.
 */
 bool AbstractProperty::isValid() const
 {
@@ -206,8 +205,7 @@ bool AbstractProperty::isValid() const
 //}
 
  /*!
- \brief returns the ModelNode to which the property belongs
- \return node to which the property belongs
+    Returns the model node to which the property belongs.
 */
 ModelNode AbstractProperty::parentModelNode() const
 {
@@ -215,15 +213,14 @@ ModelNode AbstractProperty::parentModelNode() const
 }
 
 /*!
-\brief returns the QmlObjectNode to which the property belongs
-\return node to which the property belongs
+    Returns the QmlObjectNode to which the property belongs.
 */
 QmlObjectNode AbstractProperty::parentQmlObjectNode() const
 {
     return QmlObjectNode(parentModelNode());
 }
 /*!
-  \brief returns whether the property is the default property for the model node.
+    Returns whether the property is the default property for the model node.
 */
 bool AbstractProperty::isDefaultProperty() const
 {
@@ -404,7 +401,8 @@ TypeName AbstractProperty::dynamicTypeName() const
 }
 
 /*!
-  \brief Returns if the the two property handles reference the same property in the same node
+    Returns whether \a property1 and \a property2 reference the same property in
+    the same node.
 */
 bool operator ==(const AbstractProperty &property1, const AbstractProperty &property2)
 {
@@ -414,7 +412,8 @@ bool operator ==(const AbstractProperty &property1, const AbstractProperty &prop
 }
 
 /*!
-  \brief Returns if the the two property handles do not reference the same property in the same node
+    Returns whether \a property1 and \a property2 do not reference the same
+    property in the same node.
   */
 bool operator !=(const AbstractProperty &property1, const AbstractProperty &property2)
 {
diff --git a/src/plugins/qmldesigner/designercore/model/abstractview.cpp b/src/plugins/qmldesigner/designercore/model/abstractview.cpp
index 68bf75f7f0..d56a8a4dbf 100644
--- a/src/plugins/qmldesigner/designercore/model/abstractview.cpp
+++ b/src/plugins/qmldesigner/designercore/model/abstractview.cpp
@@ -43,7 +43,7 @@ namespace QmlDesigner {
 \brief The AbstractView class provides an abstract interface that views and
 editors can implement to be notified about model changes.
 
-\see QmlDesigner::WidgetQueryView, QmlDesigner::NodeInstanceView
+\sa QmlDesigner::WidgetQueryView(), QmlDesigner::NodeInstanceView()
 */
 
 AbstractView::~AbstractView()
@@ -53,8 +53,10 @@ AbstractView::~AbstractView()
 }
 
 /*!
-\brief sets the view of the model. this is handled automatically by AbstractView::modelAttached.
-\param model new Model
+    Sets the view of a new \a model. This is handled automatically by
+    AbstractView::modelAttached().
+
+    \sa AbstractView::modelAttached()
 */
 void AbstractView::setModel(Model *model)
 {
@@ -85,9 +87,8 @@ ModelNode AbstractView::createModelNode(const TypeName &typeName,
 }
 
 
-/*! \brief returns the root model node
-\return constant root model node
-
+/*!
+    Returns the constant root model node.
 */
 
 const ModelNode AbstractView::rootModelNode() const
@@ -97,9 +98,8 @@ const ModelNode AbstractView::rootModelNode() const
 }
 
 
-/*! \brief returns the root model node
-\return root model node
-
+/*!
+    Returns the root model node.
 */
 
 ModelNode AbstractView::rootModelNode()
@@ -109,7 +109,7 @@ ModelNode AbstractView::rootModelNode()
 }
 
 /*!
-\brief sets the reference to model to a null pointer
+    Sets the reference to a model to a null pointer.
 
 */
 void AbstractView::removeModel()
@@ -137,13 +137,7 @@ WidgetInfo AbstractView::createWidgetInfo(QWidget *widget,
 }
 
 /*!
-\name Model related functions
-\{
-*/
-
-/*!
-\brief returns the model
-\return the model of the view
+    Returns the model of the view.
 */
 Model* AbstractView::model() const
 {
@@ -156,10 +150,9 @@ bool AbstractView::isAttached() const
 }
 
 /*!
-\brief is called if a view is being attached to a model
-\param model which is being attached
+Called if a view is being attached to \a model.
 The default implementation is setting the reference of the model to the view.
-\see Model::attachView
+\sa Model::attachView()
 */
 void AbstractView::modelAttached(Model *model)
 {
@@ -167,96 +160,73 @@ void AbstractView::modelAttached(Model *model)
 }
 
 /*!
-\brief is called before a view is being detached from a model
-\param model which is being detached
+Called before a view is detached from \a model.
 
-This is not called if Model::detachViewWithOutNotification is used! The default implementation
+This function is not called if Model::detachViewWithOutNotification is used.
+The default implementation
 is removing the reference to the model from the view.
 
-\see Model::detachView
+\sa Model::detachView()
 */
 void AbstractView::modelAboutToBeDetached(Model *)
 {
     removeModel();
 }
 
-//\}
-
-
 /*!
-\name Property related functions
-\{
- */
+    \enum QmlDesigner::AbstractView::PropertyChangeFlag
 
-/*!
-\fn void QmlDesigner::AbstractView::propertyAdded(const ModelNode &, const AbstractProperty &)
-\brief node notifies about that this property is added
-\param node node to which the property is added
-\param property added property
-*/
+    Notifies about changes in the abstract properties of a node:
 
+    \value  NoAdditionalChanges
+            No changes were made.
 
-/*!
-\fn void AbstractView::propertyValueChanged(const ModelNode &, const AbstractProperty& , const QVariant& , const QVariant& )
-\brief this notifies about that the value of this proeprty will be changes
-\param node node of the property
-\param property changed property
-\param newValue the variant of the new value
-\param oldValue the variant of the old value
+    \value  PropertiesAdded
+            Some properties were added.
+
+    \value  EmptyPropertiesRemoved
+            Empty properties were removed.
 */
-//\}
 
-/*!
-\name Node related functions
-\{
- */
+// Node related functions
 
 /*!
-\fn void AbstractView::nodeCreated(const ModelNode &)
-\brief this function is called if a new node was created
-\param createdNode created node
+\fn void AbstractView::nodeCreated(const ModelNode &createdNode)
+Called when the new node \a createdNode is created.
 */
 
-
 /*!
-\fn AbstractView::fileUrlChanged(const QUrl &oldBaseUrl, const QUrl &newBaseUrl)
-\brief Called when the file url (e.g. needed to to resolve relative paths against) has changed
-\param oldBaseUrl old search path
-\param newBaseUrl new search path
+Called when the file URL (that is needed to resolve relative paths against,
+for example) is changed form \a oldUrl to \a newUrl.
 */
 void AbstractView::fileUrlChanged(const QUrl &/*oldUrl*/, const QUrl &/*newUrl*/)
 {
 }
 
 /*!
-\fn void AbstractView::nodeAboutToBeRemoved(const ModelNode &)
-\brief this is called if a node will be removed
-\param removedNode to be removed node
+\fn void AbstractView::nodeAboutToBeRemoved(const ModelNode &removedNode)
+Called when the node specified by \a removedNode will be removed.
 */
 
 /*!
-\brief this is called after a propererty was removed
-\param propertyList removed property list
+Called when the properties specified by \a propertyList are removed.
 */
 void AbstractView::propertiesRemoved(const QList<AbstractProperty>& /*propertyList*/)
 {
 }
 
 /*!
-\fn void AbstractView::nodeReparented(const ModelNode &, const ModelNode &, const ModelNode &)
-\brief this is called if a node was reparented
-\param node the parent for this node will be changed
-\param oldParent old parent of the node
-\param newParent new parent of the node
+\fn void nodeReparented(const ModelNode &node, const NodeAbstractProperty &newPropertyParent, const NodeAbstractProperty &oldPropertyParent, AbstractView::PropertyChangeFlags propertyChange)
+Called when the parent of \a node will be changed from \a oldPropertyParent to
+\a newPropertyParent.
 */
 
 /*!
-\fn void QmlDesigner::AbstractView::selectedNodesChanged(const QList< ModelNode > &, const QList< ModelNode > &)
-\brief this function is called if the selection was changed
-\param selectedNodeList the new selection list
-\param lastSelectedNodeList the old selection list
+\fn void QmlDesigner::AbstractView::selectedNodesChanged(const QList<ModelNode> &selectedNodeList,
+                                                         const QList<ModelNode> &lastSelectedNodeList)
+Called when the selection is changed from \a lastSelectedNodeList to
+\a selectedNodeList.
 */
-//\}
 
 void AbstractView::auxiliaryDataChanged(const ModelNode &/*node*/, const PropertyName &/*name*/, const QVariant &/*data*/)
 {
@@ -291,8 +261,8 @@ QList<Internal::InternalNode::Pointer> toInternalNodeList(const QList<ModelNode>
 }
 
 /*!
-\brief set this list nodes to the actual selected nodes
-\param focusNodeList list the selected nodes
+    Sets the list of nodes to the actual selected nodes specified by
+    \a selectedNodeList.
 */
 void AbstractView::setSelectedModelNodes(const QList<ModelNode> &selectedNodeList)
 {
@@ -300,7 +270,7 @@ void AbstractView::setSelectedModelNodes(const QList<ModelNode> &selectedNodeLis
 }
 
 /*!
-\brief clears the selection
+    Clears the selection.
 */
 void AbstractView::clearSelectedModelNodes()
 {
@@ -308,8 +278,8 @@ void AbstractView::clearSelectedModelNodes()
 }
 
 /*!
-\brief set this list nodes to the actual selected nodes
-\return list the selected nodes
+    Sets the list of nodes to the actual selected nodes. Returns a list of the
+    selected nodes.
 */
 QList<ModelNode> AbstractView::selectedModelNodes() const
 {
@@ -317,8 +287,7 @@ QList<ModelNode> AbstractView::selectedModelNodes() const
 }
 
 /*!
-\brief adds a node to the selection list
-\param node to be added to the selection list
+    Adds \a node to the selection list.
 */
 void AbstractView::selectModelNode(const ModelNode &node)
 {
@@ -326,8 +295,7 @@ void AbstractView::selectModelNode(const ModelNode &node)
 }
 
 /*!
-\brief removes a node from the selection list
-\param node to be removed from the selection list
+    Removes \a node from the selection list.
 */
 void AbstractView::deselectModelNode(const ModelNode &node)
 {
diff --git a/src/plugins/qmldesigner/designercore/model/nodeabstractproperty.cpp b/src/plugins/qmldesigner/designercore/model/nodeabstractproperty.cpp
index 3741d4fa90..dbe3a96a81 100644
--- a/src/plugins/qmldesigner/designercore/model/nodeabstractproperty.cpp
+++ b/src/plugins/qmldesigner/designercore/model/nodeabstractproperty.cpp
@@ -136,7 +136,8 @@ QList<ModelNode> NodeAbstractProperty::allSubNodes()
 }
 
 /*!
-  \brief Returns if the the two property handles reference the same property in the same node
+    Returns whether property handles \a property1 and \a property2 reference
+    the same property in the same node.
 */
 bool operator ==(const NodeAbstractProperty &property1, const NodeAbstractProperty &property2)
 {
@@ -144,7 +145,8 @@ bool operator ==(const NodeAbstractProperty &property1, const NodeAbstractProper
 }
 
 /*!
-  \brief Returns if the the two property handles do not reference the same property in the same node
+    Returns whether the property handles \a property1 and \a property2 do not
+    reference the same property in the same node.
   */
 bool operator !=(const NodeAbstractProperty &property1, const NodeAbstractProperty &property2)
 {
diff --git a/src/plugins/qmldesigner/designercore/model/qmlobjectnode.cpp b/src/plugins/qmldesigner/designercore/model/qmlobjectnode.cpp
index 42c41dc6ab..ee8f30a823 100644
--- a/src/plugins/qmldesigner/designercore/model/qmlobjectnode.cpp
+++ b/src/plugins/qmldesigner/designercore/model/qmlobjectnode.cpp
@@ -87,11 +87,10 @@ bool QmlObjectNode::isRootModelNode() const
 }
 
 
-/*! \brief returns the value of a property based on an actual instance
-The return value is not the value in the model, but the value of a real
-instanciated instance of this object.
-\return the value of this property based on the instance
-
+/*!
+    Returns the value of the property specified by \name that is based on an
+    actual instance. The return value is not the value in the model, but the
+    value of a real instantiated instance of this object.
 */
 QVariant  QmlObjectNode::instanceValue(const PropertyName &name) const
 {
@@ -222,10 +221,8 @@ QString QmlObjectNode::expression(const PropertyName &name) const
     return propertyChanges.modelNode().bindingProperty(name).expression();
 }
 
-/*! \brief returns if ObjectNode is the BaseState
-
-\return true if the ObjectNode is in the BaseState
-
+/*!
+    Returns \c true if the ObjectNode is in the BaseState.
 */
 bool QmlObjectNode::isInBaseState() const
 {
@@ -265,10 +262,10 @@ static void removeStateOperationsForChildren(const QmlObjectNode &node)
 }
 
 
-/*! \brief Deletes this objects ModeNode and its dependencies from the model
-Every thing that belongs to this Object, the ModelNode and ChangeOperations
-are deleted from the model.
-
+/*!
+    Deletes this object's node and its dependencies from the model.
+    Everything that belongs to this Object, the ModelNode, and ChangeOperations
+    is deleted from the model.
 */
 void QmlObjectNode::destroy()
 {
@@ -282,9 +279,8 @@ void QmlObjectNode::destroy()
     modelNode().destroy();
 }
 
-/*! \brief Returns a list of all states that are affecting this object.
-
-\return list of states affecting this object
+/*!
+    Returns a list of states the affect this object.
 */
 
 QList<QmlModelState> QmlObjectNode::allAffectingStates() const
@@ -301,9 +297,8 @@ QList<QmlModelState> QmlObjectNode::allAffectingStates() const
     return returnList;
 }
 
-/*! \brief Returns a list of all state operations that are affecting this object.
-
-\return list of state operations affecting this object
+/*!
+    Returns a list of all state operations that affect this object.
 */
 
 QList<QmlModelStateOperation> QmlObjectNode::allAffectingStatesOperations() const
@@ -360,8 +355,9 @@ QList<QmlModelState> QmlObjectNode::allDefinedStates() const
 }
 
 
-/*! \brief Removes a variant property of this object from the model
-
+/*!
+    Removes a variant property of the object specified by \a name from the
+    model.
 */
 
 void  QmlObjectNode::removeVariantProperty(const PropertyName &name)
diff --git a/src/plugins/qmldesigner/designercore/model/qmlstate.cpp b/src/plugins/qmldesigner/designercore/model/qmlstate.cpp
index 21d343a953..44909ab520 100644
--- a/src/plugins/qmldesigner/designercore/model/qmlstate.cpp
+++ b/src/plugins/qmldesigner/designercore/model/qmlstate.cpp
@@ -161,9 +161,9 @@ QList<QmlModelStateOperation> QmlModelState::stateOperations() const
 }
 
 
-/*! \brief Add a ChangeSet for the specified ModelNode to this state
-  The new ChangeSet if only added if no ChangeSet for the ModelNode
-  does not exist, yet.
+/*!
+    Adds a change set for \a node to this state, but only if it does not
+    already exist.
 */
 
 void QmlModelState::addChangeSetIfNotExists(const ModelNode &node)
@@ -205,9 +205,8 @@ void QmlModelState::removePropertyChanges(const ModelNode &node)
 
 
 
-/*! \brief Returns if this state affects the specified ModelNode
-
-\return true if this state affects the specifigied ModelNode
+/*!
+     Returns \c true if this state affects \a node.
 */
 bool QmlModelState::affectsModelNode(const ModelNode &node) const
 {
@@ -260,9 +259,8 @@ void QmlModelState::destroy()
     modelNode().destroy();
 }
 
-/*! \brief Returns if this state is the base state
-
-\return true if this state is the base state
+/*!
+    Returns \c true if this state is the base state.
 */
 
 bool QmlModelState::isBaseState() const