Commit 4f07bd68 authored by Leena Miettinen's avatar Leena Miettinen
Browse files

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: default avatarThomas Hartmann <Thomas.Hartmann@digia.com>
parent 06ba109c
......@@ -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)
{
......
......@@ -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)
{
......
......@@ -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)
{
......
......@@ -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)
......
......@@ -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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment