From 2226bbe49f1442a308b8cffc2582d2ae21957f02 Mon Sep 17 00:00:00 2001 From: Sabine Schmaltz Date: Sat, 8 Mar 2014 23:08:34 +0100 Subject: [PATCH] attempt at improving documentation, questions to be removed after clarification --HG-- branch : develop --- src/xml/vdomdocument.h | 407 +++++++++++++++++++++-------------------- 1 file changed, 211 insertions(+), 196 deletions(-) diff --git a/src/xml/vdomdocument.h b/src/xml/vdomdocument.h index e808e614e..f036a925b 100644 --- a/src/xml/vdomdocument.h +++ b/src/xml/vdomdocument.h @@ -6,8 +6,8 @@ ** ** @brief ** @copyright - ** This source code is part of the Valentine project, a pattern making - ** program, whose allow create and modeling patterns of clothing. + ** This source code is part of the Valentina project, a pattern making + ** program that allows creating and modelling patterns of clothing. ** Copyright (C) 2013 Valentina project ** All Rights Reserved. ** @@ -41,7 +41,8 @@ namespace Document { /** - * @brief The Document enum types parse. + * @brief Flags to determine the parsing mode in VDomDocument::Parse() and + * related functions. */ enum Document { LiteParse, FullParse}; Q_DECLARE_FLAGS(Documents, Document) @@ -54,403 +55,417 @@ Q_DECLARE_OPERATORS_FOR_FLAGS(Document::Documents) #endif /** - * @brief The VDomDocument class working with pattern file. + * @brief The VDomDocument class represents a Valentina document (.val file). + * + * A Valentina document describes the construction of a sewing pattern. The + * information is stored in XML format. By parsing a VDomDocument, the contained + * pattern is rendered to a Valentina graphics scene (VMainGraphicsScene). + * + * A sewing pattern consists of increments (TODO: what are increments?) and one + * or more pattern pieces. + * + * A pattern piece contains + * 1) auxiliary pattern construction elements (calculation), + * 2) pattern construction elements (modeling), and + * 3) special markers, e.g. seam allowances (details). + * Of these, 2) and 3) are visible in the final pattern (draw mode 'Modeling'), + * 1) is only displayed when editing (draw mode 'Calculation') the pattern. */ class VDomDocument : public QObject, public QDomDocument { Q_OBJECT public: - /** - * @brief VDomDocument constructor. - * @param data container with variables. - * @param comboBoxDraws combobox for pattern peaces names. - * @param mode draw mode. - */ - VDomDocument(VContainer *data, QComboBox *comboBoxDraws, Draw::Draws *mode, QObject *parent = 0); - /** - * @brief VDomDocument constructor. - * @param name pattern peace name. - * @param data container with variables. - * @param comboBoxDraws combobox for pattern peaces names. - * @param mode draw mode. - */ - VDomDocument(const QString& name, VContainer *data, QComboBox *comboBoxDraws, Draw::Draws *mode, - QObject *parent = 0); - /** - * @brief VDomDocument constructor. - * @param doc dom document container type. - * @param data container with variables. - * @param comboBoxDraws combobox for pattern peaces names. - * @param mode draw mode. - */ - VDomDocument(const QDomDocumentType& doctype, VContainer *data, QComboBox *comboBoxDraws, - Draw::Draws *mode, QObject *parent = 0); - ~VDomDocument(){} /** - * @brief elementById find element by id. + * @param data container with variables + * @param comboBoxDraws pointer to the ComboBox that will hold the pattern piece names + * @param mode draw mode + * @param parent TODO: what about this? do we ever use this? + */ + VDomDocument(VContainer *data, QComboBox *comboBoxDraws, Draw::Draws *mode, QObject *parent = 0); + /** + * @param name pattern piece name + * @param data container with variables + * @param comboBoxDraws pointer to the ComboBox that will hold the pattern piece names + * @param mode draw mode + * @param parent + */ + VDomDocument(const QString& name, VContainer *data, QComboBox *comboBoxDraws, Draw::Draws *mode, + QObject *parent = 0); + /** + * @param doctype dom document container type + * @param data container with variables + * @param comboBoxDraws pointer to the ComboBox that will hold the pattern piece names + * @param mode draw mode + * @param parent TODO: ? + */ + VDomDocument(const QDomDocumentType& doctype, VContainer *data, QComboBox *comboBoxDraws, + Draw::Draws *mode, QObject *parent = 0); + ~VDomDocument(){} + /** + * @brief Finds an element by id. * @param id value id attribute. * @return dom element. */ QDomElement elementById(const QString& id); /** - * @brief removeAllChilds remove all tag childs. - * @param element tag. + * @brief Removes all children of a given element tag. RENAME: removeAllChildren? + * @param element tag */ void removeAllChilds(QDomElement &element); /** - * @brief CreateEmptyFile create minimal empty file. + * @brief Create a minimal empty file. */ void CreateEmptyFile(); /** - * @brief ChangeActivDraw set new pattern peace name. - * @param name new name. - * @param parse parser file mode. + * @brief Select pattern piece based on name. RENAME: ChangeActiveDraw? + * @param name pattern piece name + * @param parse parsing mode */ void ChangeActivDraw(const QString& name, const Document::Documents &parse = Document::FullParse); /** - * @brief GetNameActivDraw return current pattern peace name. - * @return pattern peace name. + * @brief Get selected pattern piece name. RENAME: GetNameOfActiveDraw? + * @return name of the active pattern piece */ inline QString GetNameActivDraw() const {return nameActivDraw;} /** - * @brief GetActivDrawElement return draw tag for current pattern peace. - * @param element draw tag. - * @return true if found. + * @brief Finds the draw element of the selected pattern piece and returns it by reference. RENAME: GetActiveDrawElement? + * @param element the returned draw element -- not used as input + * @return true if found */ bool GetActivDrawElement(QDomElement &element); /** - * @brief GetActivCalculationElement return calculation tag for current pattern peace. - * @param element calculation tag. - * @return true if found. + * @brief Finds the calculation element for the selected pattern piece and returns it by reference. RENAME: GetActiveCalculationElement? + * @param element the returned calculation element -- not used as input + * @return true if found */ bool GetActivCalculationElement(QDomElement &element); /** - * @brief GetActivModelingElement return modeling tag for current pattern peace. - * @param element modeling tag - * @return true if found. + * @brief Finds the modeling element for the selected pattern piece and returns it by reference. RENAME: GetActiveModelingElement? + * @param element the returned modeling element -- not used as input + * @return true if found */ bool GetActivModelingElement(QDomElement &element); /** - * @brief GetActivDetailsElement return details tag for current pattern peace. - * @param element details tag. - * @return true if found. + * @brief Finds the details element for the selected pattern piece and returns it by reference. RENAME: GetActiveDetailsElement? + * @param element the returned details element -- not used as input + * @return true if found */ bool GetActivDetailsElement(QDomElement &element); /** - * @brief appendDraw add new pattern peace structure to the file. - * @param name pattern peace name. - * @return true if success. + * @brief Adds a new pattern piece to the document. NOTE: inconsistent capitalization + * @param name pattern piece name. + * @return true if successful */ bool appendDraw(const QString& name); /** - * @brief SetNameDraw change current pattern peace. - * @param name pattern peace name. - * @return true if success. + * @brief Sets the name of the selected pattern piece. RENAME: SetNameOfActiveDraw? + * @param name pattern piece name. + * @return true if successful */ bool SetNameDraw(const QString& name); /** - * @brief Parse parse file. - * @param parse parser file mode. - * @param sceneDraw pointer to draw scene. - * @param sceneDetail pointer to details scene. + * @brief Parse the document, resulting in a rendering of the pattern in the graphics scenes. + * @param parse parsing mode + * @param sceneDraw pointer to draw scene + * @param sceneDetail pointer to details scene */ void Parse(const Document::Documents &parse, VMainGraphicsScene *sceneDraw, VMainGraphicsScene *sceneDetail); /** - * @brief getTools return list of tools pointers. - * @return list. + * @brief Return a list of tool pointers. Q: What for? Which tool pointers? + * @return list of tool pointers */ inline QHash* getTools() {return &tools;} /** - * @brief getTool return tool from tool list. - * @param id tool id. - * @return tool. + * @brief Get a tool from the tool list by id. NOTE: inconsistent capitalization + * @param id tool id + * @return tool */ VDataTool* getTool(const qint64 &id); /** - * @brief getHistory return list with list of history records. - * @return list of history records. + * @brief Return a list of history record vectors. TODO: describe more about history + * @return list of history record vectors */ inline QVector *getHistory() {return &history;} /** - * @brief getCursor return cursor. - * @return cursor. + * @brief Returns the cursor. TODO: why is cursor an int? It's not the cursor position obviously, but what is it? + * @return cursor */ inline qint64 getCursor() const {return cursor;} /** - * @brief setCursor set cursor. - * @param value cursor. + * @brief Set the cursor. TODO: like above. NOTE: inconsistent capitalization + * @param value cursor */ void setCursor(const qint64 &value); /** - * @brief setCurrentData set current data set. + * @brief Set current data set. TODO: very unclear what this does, possibly bad naming. NOTE: inconsistent capitalization */ void setCurrentData(); /** - * @brief AddTool add tool to list tools. + * @brief Add the given tool to the tools list. * @param id tool id. * @param tool tool. */ void AddTool(const qint64 &id, VDataTool *tool); /** - * @brief UpdateToolData update tool in list tools. - * @param id tool id. - * @param data container with variables. + * @brief Updates a given tool in the tools list. + * @param id id of the tool to update + * @param data container with variables */ void UpdateToolData(const qint64 &id, VContainer *data); /** - * @brief IncrementReferens increment reference parent objects. - * @param id parent object id. + * @brief Increment reference parent objects. TODO: unclear what it does, seems to work on some tool given by id RENAME: IncrementReference + * @param id parent object id */ void IncrementReferens(qint64 id) const; /** - * @brief DecrementReferens decrement reference parent objects. - * @param id parent object id. + * @brief Decrement reference parent objects. TODO: see above RENAME: like above + * @param id parent object id */ void DecrementReferens(qint64 id) const; /** - * @brief TestUniqueId test exist unique id in pattern file. Each id must be unique. + * @brief Throws an exception if there exists a duplicate id in the pattern file. */ void TestUniqueId() const; /** - * @brief GetParametrLongLong return long long value of attribute. - * @param domElement tag in xml tree. - * @param name attribute name. - * @return long long value. + * @brief Return long long value of attribute. TODO: what is a long long value? TODO: what is an attribute? RENAME: GetParameterLongLong + * @param domElement tag in xml tree + * @param name attribute name + * @return long long value */ qint64 GetParametrLongLong(const QDomElement& domElement, const QString &name, const QString &defValue) const; /** - * @brief GetParametrString return string value of attribute. - * @param domElement tag in xml tree. - * @param name attribute name. - * @return attribute value. + * @brief Return string value of attribute. RENAME: see above + * @param domElement tag in xml tree + * @param name attribute name + * @return attribute value */ QString GetParametrString(const QDomElement& domElement, const QString &name, const QString &defValue) const; /** - * @brief GetParametrDouble return double value of attribute. - * @param domElement tag in xml tree. - * @param name attribute name. - * @return double value. + * @brief Return double value of attribute. + * @param domElement tag in xml tree + * @param name attribute name + * @return double value */ qreal GetParametrDouble(const QDomElement& domElement, const QString &name, const QString &defValue) const; /** - * @brief SPointActiveDraw return id base point current pattern peace. - * @return id base point. + * @brief Returns the id of the base point of the current pattern piece. + * @return id of base point */ qint64 SPointActiveDraw(); - bool isPatternModified() const; - void setPatternModified(bool value); + bool isPatternModified() const; // NOTE: inconsistent capitalization + void setPatternModified(bool value); // NOTE: inconsistent capitalization QString UniqueTagText(const QString &tagName, const QString &defVal = QString()); signals: /** - * @brief ChangedActivDraw change active pattern peace. - * @param newName new pattern peace name. + * @brief The active pattern piece was changed. RENAME: ChangedActiveDraw + * @param newName new pattern piece name */ void ChangedActivDraw(const QString &newName); /** - * @brief ChangedNameDraw save new name active pattern peace. - * @param oldName old name. - * @param newName new name. + * @brief The name of the selected pattern piece was changed. + * @param oldName old name + * @param newName new name */ void ChangedNameDraw(const QString &oldName, const QString &newName); /** - * @brief FullUpdateFromFile update tool data form file. + * @brief Update tool data from file. TODO: has tool data update been done before emitting or must that be done after the signal is emitted? */ void FullUpdateFromFile(); /** - * @brief patternChanged emit if we have unsaved change. + * @brief Emit if there exists an unsaved change to the pattern document. */ - void patternChanged(); + void patternChanged(); //NOTE: inconsistent capitalization /** - * @brief ShowTool highlight tool. - * @param id tool id. - * @param color highlight color. - * @param enable enable or disable highlight. + * @brief Highlight tool. + * @param id tool id + * @param color highlight color + * @param enable enable or disable highlight */ void ShowTool(qint64 id, Qt::GlobalColor color, bool enable); /** - * @brief ChangedCursor change cursor position. - * @param id tool id. + * @brief The cursor position has changed. + * @param id tool id */ void ChangedCursor(qint64 id); public slots: /** - * @brief FullUpdateTree lite parse file. + * @brief Perform a lite parse run on the pattern document. */ void FullUpdateTree(); /** - * @brief haveLiteChange we have unsaved change. + * @brief Sets that we have an unsaved change on the pattern file. Emits patternChanged(). */ - void haveLiteChange(); + void haveLiteChange(); //NOTE: inconsistent capitalization /** - * @brief ShowHistoryTool hightlight tool. - * @param id tool id. - * @param color hightlight color. - * @param enable enable or diasable hightlight. + * @brief Highlights a tool by id. + * @param id tool id + * @param color highlight color + * @param enable enable or disable highlight */ void ShowHistoryTool(qint64 id, Qt::GlobalColor color, bool enable); private: Q_DISABLE_COPY(VDomDocument) /** - * @brief map use for finding element by id. + * @brief Map used for finding element by id. */ QHash map; /** - * @brief nameActivDraw name current pattern peace. + * @brief Name of the selected pattern piece. */ QString nameActivDraw; /** - * @brief data container with data. + * @brief Container with pattern document data. */ VContainer *data; /** - * @brief tools list with pointer on tools. + * @brief Tools map with pointers to tools. */ QHash tools; /** - * @brief history history records. + * @brief Tool history record. */ QVector history; /** - * @brief cursor cursor keep id tool after which we will add new tool in file. + * @brief Cursor keep id tool after which we will add new tool in file. TODO: very unclear what does that mean? */ qint64 cursor; /** - * @brief comboBoxDraws combobox with pattern peace names. + * @brief A pointer to the QComboBox used to select pattern piece names. */ QComboBox *comboBoxDraws; /** - * @brief mode current draw mode. + * @brief Current draw mode. */ Draw::Draws *mode; /** - * @brief fileModified true if exist change in file. + * @brief True if there is an unsaved change in the document. */ bool patternModified; /** - * @brief find find element by id. - * @param node node. - * @param id id value. - * @return true if found. + * @brief Find element by id. + * @param node node + * @param id id value + * @return true if found */ bool find(const QDomElement &node, const QString& id); /** - * @brief CheckNameDraw check if exist pattern peace with this name. - * @param name pattern peace name. - * @return true if exist. + * @brief Checks whether there exists a pattern piece with the given name. + * @param name pattern piece name + * @return true if it exists */ bool CheckNameDraw(const QString& name) const; /** - * @brief SetActivDraw set current pattern peace. - * @param name pattern peace name. + * @brief Set selected pattern piece. RENAME: SetActiveDraw + * @param name pattern piece name */ void SetActivDraw(const QString& name); /** - * @brief GetActivNodeElement find element in current pattern peace by name. - * @param name name tag. - * @param element element. - * @return true if found. + * @brief Finds an element in the current pattern piece by name. RENAME: like above + * @param name name tag + * @param element element returned by reference + * @return true if found */ bool GetActivNodeElement(const QString& name, QDomElement& element); /** - * @brief ParseDrawElement parse draw tag. - * @param sceneDraw draw scene. - * @param sceneDetail details scene. - * @param node node. - * @param parse parser file mode. + * @brief Parses a draw tag. + * @param sceneDraw draw scene + * @param sceneDetail details scene + * @param node node + * @param parse parse mode */ void ParseDrawElement(VMainGraphicsScene *sceneDraw, VMainGraphicsScene *sceneDetail, const QDomNode& node, const Document::Documents &parse); /** - * @brief ParseDrawMode parse draw tag with draw mode. - * @param sceneDraw draw scene. - * @param sceneDetail details scene. - * @param node node. - * @param parse parser file mode. - * @param mode draw mode. + * @brief Parses a draw tag in draw mode. + * @param sceneDraw draw scene + * @param sceneDetail details scene + * @param node node + * @param parse parse mode + * @param mode draw mode */ void ParseDrawMode(VMainGraphicsScene *sceneDraw, VMainGraphicsScene *sceneDetail, const QDomNode& node, const Document::Documents &parse, const Draw::Draws &mode); /** - * @brief ParseDetailElement parse detail tag. - * @param sceneDetail detail scene. - * @param domElement tag in xml tree. - * @param parse parser file mode. + * @brief Parses a detail element tag. + * @param sceneDetail details scene + * @param domElement tag in XML tree + * @param parse parse mode */ void ParseDetailElement(VMainGraphicsScene *sceneDetail, const QDomElement &domElement, const Document::Documents &parse); /** - * @brief ParseDetails parse details tag. - * @param sceneDetail detail scene. - * @param domElement tag in xml tree. - * @param parse parser file mode. + * @brief Parses a details tag. + * @param sceneDetail details scene + * @param domElement tag in XML tree + * @param parse parse mode */ void ParseDetails(VMainGraphicsScene *sceneDetail, const QDomElement &domElement, const Document::Documents &parse); /** - * @brief ParsePointElement parse point tag. - * @param scene scene. - * @param domElement tag in xml tree. - * @param parse parser file mode. - * @param type type of point. - * @param mode draw mode. + * @brief Parses a point element tag. + * @param scene scene + * @param domElement tag in XML tree + * @param parse parse mode + * @param type type of point + * @param mode draw mode */ void ParsePointElement(VMainGraphicsScene *scene, const QDomElement& domElement, const Document::Documents &parse, const QString &type); /** - * @brief ParseLineElement parse line tag. - * @param scene scene. - * @param domElement tag in xml tree. - * @param parse parser file mode. - * @param mode draw mode. + * @brief Parses a line element tag. + * @param scene scene + * @param domElement tag in XML tree + * @param parse parse mode + * @param mode draw mode */ void ParseLineElement(VMainGraphicsScene *scene, const QDomElement& domElement, const Document::Documents &parse); /** - * @brief ParseSplineElement parse spline tag. - * @param scene scene. - * @param domElement tag in xml tree. - * @param parse parser file mode. - * @param type type of spline. - * @param mode draw mode. + * @brief Parses a spline element tag. + * @param scene scene + * @param domElement tag in XML tree + * @param parse parse mode. + * @param type type of spline + * @param mode draw mode */ void ParseSplineElement(VMainGraphicsScene *scene, const QDomElement& domElement, const Document::Documents &parse, const QString& type); /** - * @brief ParseArcElement parse arc tag. - * @param scene scene. - * @param domElement tag in xml tree. - * @param parse parser file mode. - * @param type type of spline. - * @param mode draw mode. + * @brief Parses an arc element tag. + * @param scene scene + * @param domElement tag in XML tree + * @param parse parse mode + * @param type type of spline + * @param mode draw mode */ void ParseArcElement(VMainGraphicsScene *scene, const QDomElement& domElement, const Document::Documents &parse, const QString& type); /** - * @brief ParseToolsElement parse tools tag. - * @param scene scene. - * @param domElement tag in xml tree. - * @param parse parser file mode. - * @param type type of spline. + * @brief Parses a tools element tag. + * @param scene scene + * @param domElement tag in XML tree + * @param parse parse mode + * @param type type of spline */ void ParseToolsElement(VMainGraphicsScene *scene, const QDomElement& domElement, const Document::Documents &parse, const QString& type); /** - * @brief ParseIncrementsElement parse increments tag. - * @param node tag in xml tree. + * @brief Parses an increments element tag. + * @param node tag in XML tree */ void ParseIncrementsElement(const QDomNode& node); /** - * @brief GetParametrId return value id attribute. - * @param domElement tag in xml tree. - * @return id value. + * @brief Returns the id attribute of the given element. RENAME: GetParameterId? + * @param domElement tag in XML tree + * @return id value */ qint64 GetParametrId(const QDomElement& domElement) const; /** - * @brief CollectId recursive function, try find id attribute in file. Throw exclusion if find not unique. - * @param node tag in xml tree. - * @param vector list with ids. + * @brief Recursively collects all id attribute in file. Throws exception if a duplicate is found. (TODO: which exception?) + * @param node tag in XML tree + * @param vector list with ids */ void CollectId(const QDomElement &node, QVector &vector)const; };