feedc0de/qt-creator
1
0
Fork 0
forked from qt-creator/qt-creator
Code Pull Requests Activity

Doc: edit qmldesigner designercore model API docs

Browse Source 
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>
This commit is contained in:
Leena Miettinen
2013-09-10 12:43:43 +02:00
parent 06ba109c0b
commit 4f07bd688a
5 changed files with 90 additions and 127 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
src/plugins/qmldesigner/designercore/model/abstractproperty.cpp
View File

@@ -120,10 +120,9 @@ AbstractView *AbstractProperty::view() const
} }
/*! /*!
\brief AbstractProperty is a value holder for a property Holds a value for a property. Returns the value of the property.
\return 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 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 is valid. This function is not overloaded for
subclasses. 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 bool AbstractProperty::isValid() const
{ {
@@ -206,8 +205,7 @@ bool AbstractProperty::isValid() const
//} //}
/*! /*!
\brief returns the ModelNode to which the property belongs Returns the model node to which the property belongs.
\return node to which the property belongs
*/ */
ModelNode AbstractProperty::parentModelNode() const ModelNode AbstractProperty::parentModelNode() const
{ {
@@ -215,15 +213,14 @@ ModelNode AbstractProperty::parentModelNode() const
} }
/*! /*!
\brief returns the QmlObjectNode to which the property belongs Returns the QmlObjectNode to which the property belongs.
\return node to which the property belongs
*/ */
QmlObjectNode AbstractProperty::parentQmlObjectNode() const QmlObjectNode AbstractProperty::parentQmlObjectNode() const
{ {
return QmlObjectNode(parentModelNode()); 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 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) 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) bool operator !=(const AbstractProperty &property1, const AbstractProperty &property2)
{ {

138
src/plugins/qmldesigner/designercore/model/abstractview.cpp
View File

@@ -43,7 +43,7 @@ namespace QmlDesigner {
\brief The AbstractView class provides an abstract interface that views and \brief The AbstractView class provides an abstract interface that views and
editors can implement to be notified about model changes. editors can implement to be notified about model changes.
\see QmlDesigner::WidgetQueryView, QmlDesigner::NodeInstanceView \sa QmlDesigner::WidgetQueryView(), QmlDesigner::NodeInstanceView()
*/ */
AbstractView::~AbstractView() AbstractView::~AbstractView()
@@ -53,8 +53,10 @@ AbstractView::~AbstractView()
} }
/*! /*!
\brief sets the view of the model. this is handled automatically by AbstractView::modelAttached. Sets the view of a new \a model. This is handled automatically by
\param model new Model AbstractView::modelAttached().
\sa AbstractView::modelAttached()
*/ */
void AbstractView::setModel(Model *model) 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 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() 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() void AbstractView::removeModel()
@@ -137,13 +137,7 @@ WidgetInfo AbstractView::createWidgetInfo(QWidget *widget,
} }
/*! /*!
\name Model related functions Returns the model of the view.
\{
*/
/*!
\brief returns the model
\return the model of the view
*/ */
Model* AbstractView::model() const Model* AbstractView::model() const
{ {
@@ -156,10 +150,9 @@ bool AbstractView::isAttached() const
} }
/*! /*!
\brief is called if a view is being attached to a model Called if a view is being attached to \a model.
\param model which is being attached
The default implementation is setting the reference of the model to the view. The default implementation is setting the reference of the model to the view.
\see Model::attachView \sa Model::attachView()
*/ */
void AbstractView::modelAttached(Model *model) 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 Called before a view is detached from \a model.
\param model which is being detached
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. is removing the reference to the model from the view.
\see Model::detachView \sa Model::detachView()
*/ */
void AbstractView::modelAboutToBeDetached(Model *) void AbstractView::modelAboutToBeDetached(Model *)
{ {
removeModel(); removeModel();
} }
//\} /*!
\enum QmlDesigner::AbstractView::PropertyChangeFlag
Notifies about changes in the abstract properties of a node:
\value NoAdditionalChanges
No changes were made.
\value PropertiesAdded
Some properties were added.
\value EmptyPropertiesRemoved
Empty properties were removed.
*/
// Node related functions
/*! /*!
\name Property related functions \fn void AbstractView::nodeCreated(const ModelNode &createdNode)
\{ Called when the new node \a createdNode is created.
*/ */
/*! /*!
\fn void QmlDesigner::AbstractView::propertyAdded(const ModelNode &, const AbstractProperty &) Called when the file URL (that is needed to resolve relative paths against,
\brief node notifies about that this property is added for example) is changed form \a oldUrl to \a newUrl.
\param node node to which the property is added
\param property added property
*/
/*!
\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
*/
//\}
/*!
\name 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 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
*/ */
void AbstractView::fileUrlChanged(const QUrl &/*oldUrl*/, const QUrl &/*newUrl*/) void AbstractView::fileUrlChanged(const QUrl &/*oldUrl*/, const QUrl &/*newUrl*/)
{ {
} }
/*! /*!
\fn void AbstractView::nodeAboutToBeRemoved(const ModelNode &) \fn void AbstractView::nodeAboutToBeRemoved(const ModelNode &removedNode)
\brief this is called if a node will be removed Called when the node specified by \a removedNode will be removed.
\param removedNode to be removed node
*/ */
/*! /*!
\brief this is called after a propererty was removed Called when the properties specified by \a propertyList are removed.
\param propertyList removed property list
*/ */
void AbstractView::propertiesRemoved(const QList<AbstractProperty>& /*propertyList*/) void AbstractView::propertiesRemoved(const QList<AbstractProperty>& /*propertyList*/)
{ {
} }
/*! /*!
\fn void AbstractView::nodeReparented(const ModelNode &, const ModelNode &, const ModelNode &) \fn void nodeReparented(const ModelNode &node, const NodeAbstractProperty &newPropertyParent, const NodeAbstractProperty &oldPropertyParent, AbstractView::PropertyChangeFlags propertyChange)
\brief this is called if a node was reparented Called when the parent of \a node will be changed from \a oldPropertyParent to
\param node the parent for this node will be changed \a newPropertyParent.
\param oldParent old parent of the node
\param newParent new parent of the node
*/ */
/*! /*!
\fn void QmlDesigner::AbstractView::selectedNodesChanged(const QList< ModelNode > &, const QList< ModelNode > &) \fn void QmlDesigner::AbstractView::selectedNodesChanged(const QList<ModelNode> &selectedNodeList,
\brief this function is called if the selection was changed const QList<ModelNode> &lastSelectedNodeList)
\param selectedNodeList the new selection list Called when the selection is changed from \a lastSelectedNodeList to
\param lastSelectedNodeList the old selection list \a selectedNodeList.
*/ */
//\}
void AbstractView::auxiliaryDataChanged(const ModelNode &/*node*/, const PropertyName &/*name*/, const QVariant &/*data*/) 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 Sets the list of nodes to the actual selected nodes specified by
\param focusNodeList list the selected nodes \a selectedNodeList.
*/ */
void AbstractView::setSelectedModelNodes(const QList<ModelNode> &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() void AbstractView::clearSelectedModelNodes()
{ {
@@ -308,8 +278,8 @@ void AbstractView::clearSelectedModelNodes()
} }
/*! /*!
\brief set this list nodes to the actual selected nodes Sets the list of nodes to the actual selected nodes. Returns a list of the
\return list the selected nodes selected nodes.
*/ */
QList<ModelNode> AbstractView::selectedModelNodes() const QList<ModelNode> AbstractView::selectedModelNodes() const
{ {
@@ -317,8 +287,7 @@ QList<ModelNode> AbstractView::selectedModelNodes() const
} }
/*! /*!
\brief adds a node to the selection list Adds \a node to the selection list.
\param node to be added to the selection list
*/ */
void AbstractView::selectModelNode(const ModelNode &node) void AbstractView::selectModelNode(const ModelNode &node)
{ {
@@ -326,8 +295,7 @@ void AbstractView::selectModelNode(const ModelNode &node)
} }
/*! /*!
\brief removes a node from the selection list Removes \a node from the selection list.
\param node to be removed from the selection list
*/ */
void AbstractView::deselectModelNode(const ModelNode &node) void AbstractView::deselectModelNode(const ModelNode &node)
{ {

6
src/plugins/qmldesigner/designercore/model/nodeabstractproperty.cpp
View File

@@ -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) 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) bool operator !=(const NodeAbstractProperty &property1, const NodeAbstractProperty &property2)
{ {

38
src/plugins/qmldesigner/designercore/model/qmlobjectnode.cpp
View File

@@ -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 Returns the value of the property specified by \name that is based on an
instanciated instance of this object. actual instance. The return value is not the value in the model, but the
\return the value of this property based on the instance value of a real instantiated instance of this object.
*/ */
QVariant QmlObjectNode::instanceValue(const PropertyName &name) const QVariant QmlObjectNode::instanceValue(const PropertyName &name) const
{ {
@@ -222,10 +221,8 @@ QString QmlObjectNode::expression(const PropertyName &name) const
return propertyChanges.modelNode().bindingProperty(name).expression(); return propertyChanges.modelNode().bindingProperty(name).expression();
} }
/*! \brief returns if ObjectNode is the BaseState /*!
Returns \c true if the ObjectNode is in the BaseState.
\return true if the ObjectNode is in the BaseState
*/ */
bool QmlObjectNode::isInBaseState() const 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 Deletes this object's node and its dependencies from the model.
are deleted from the model. Everything that belongs to this Object, the ModelNode, and ChangeOperations
is deleted from the model.
*/ */
void QmlObjectNode::destroy() void QmlObjectNode::destroy()
{ {
@@ -282,9 +279,8 @@ void QmlObjectNode::destroy()
modelNode().destroy(); modelNode().destroy();
} }
/*! \brief Returns a list of all states that are affecting this object. /*!
Returns a list of states the affect this object.
\return list of states affecting this object
*/ */
QList<QmlModelState> QmlObjectNode::allAffectingStates() const QList<QmlModelState> QmlObjectNode::allAffectingStates() const
@@ -301,9 +297,8 @@ QList<QmlModelState> QmlObjectNode::allAffectingStates() const
return returnList; return returnList;
} }
/*! \brief Returns a list of all state operations that are affecting this object. /*!
Returns a list of all state operations that affect this object.
\return list of state operations affecting this object
*/ */
QList<QmlModelStateOperation> QmlObjectNode::allAffectingStatesOperations() const 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) void QmlObjectNode::removeVariantProperty(const PropertyName &name)

16
src/plugins/qmldesigner/designercore/model/qmlstate.cpp
View File

@@ -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 Adds a change set for \a node to this state, but only if it does not
does not exist, yet. already exist.
*/ */
void QmlModelState::addChangeSetIfNotExists(const ModelNode &node) 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 /*!
Returns \c true if this state affects \a node.
\return true if this state affects the specifigied ModelNode
*/ */
bool QmlModelState::affectsModelNode(const ModelNode &node) const bool QmlModelState::affectsModelNode(const ModelNode &node) const
{ {
@@ -260,9 +259,8 @@ void QmlModelState::destroy()
modelNode().destroy(); modelNode().destroy();
} }
/*! \brief Returns if this state is the base state /*!
Returns \c true if this state is the base state.
\return true if this state is the base state
*/ */
bool QmlModelState::isBaseState() const bool QmlModelState::isBaseState() const