From 904e73cbfa571377ab1860ba7d5a54119ab909e0 Mon Sep 17 00:00:00 2001 From: Aleks Kissinger Date: Wed, 2 Jan 2019 17:38:38 +0100 Subject: added some documentation to the source code --- src/data/delimitedstringvalidator.h | 14 ++++++++++++++ src/data/edge.h | 8 ++++++-- src/data/graphelementdata.h | 6 ++++++ src/data/graphelementproperty.h | 37 ++++++++++++++++++++++++++++++++++--- src/gui/exportdialog.h | 4 ++++ src/gui/latexprocess.h | 5 +++++ src/gui/previewwindow.h | 5 +++++ src/gui/styleeditor.h | 8 ++++++-- 8 files changed, 80 insertions(+), 7 deletions(-) diff --git a/src/data/delimitedstringvalidator.h b/src/data/delimitedstringvalidator.h index 654e4ab..b4ed3bd 100644 --- a/src/data/delimitedstringvalidator.h +++ b/src/data/delimitedstringvalidator.h @@ -19,6 +19,10 @@ /*! * A string validator which keeps curly braces matched. Used in various places * to ensure the user doesn't make non-parseable .tikz or .tikzstyles files. + * + * Its validation function will return Acceptable if all curly braces are matched + * properly, Intermediate if all braces are matched except for possibly some opening + * curly braces, and Invalid if there are unmatched closing curly braces. */ #ifndef DELIMITEDSTRINGVALIDATOR_H @@ -34,8 +38,18 @@ class DelimitedStringValidator : public QValidator public: DelimitedStringValidator(QObject *parent); QValidator::State validate(QString &input, int &/*pos*/) const override; + + /*! + * \brief fixup adds curly braces until all braces are matched (if possible) + * \param input + */ void fixup(QString &input) const override; private: + /*! + * \brief braceDepth computes the final (non-escaped) curly-brace depth of a given string + * \param input a string + * \return the final brace depth, or -1 if the depth *ever* drops below 0 + */ int braceDepth(QString input) const; }; diff --git a/src/data/edge.h b/src/data/edge.h index 5d26b3e..27d5bef 100644 --- a/src/data/edge.h +++ b/src/data/edge.h @@ -16,6 +16,10 @@ along with this program. If not, see . */ +/*! + * Class representing an edge in a Graph. + */ + #ifndef EDGE_H #define EDGE_H @@ -30,8 +34,8 @@ class Edge : public QObject { Q_OBJECT public: - explicit Edge(Node *s, Node *t, QObject *parent = 0); - Edge *copy(QMap *nodeTable = 0); + explicit Edge(Node *s, Node *t, QObject *parent = nullptr); + Edge *copy(QMap *nodeTable = nullptr); Node *source() const; Node *target() const; diff --git a/src/data/graphelementdata.h b/src/data/graphelementdata.h index b1311d7..dce0d46 100644 --- a/src/data/graphelementdata.h +++ b/src/data/graphelementdata.h @@ -16,6 +16,12 @@ along with this program. If not, see . */ +/*! + * A list of GraphElementProperty objects, which convenience methods + * for lookup, deletion, re-ordering, etc. It inherits QAbstractItemModel + * so it can be used as the model for a QTreeView in the StyleEditor. + */ + #ifndef GRAPHELEMENTDATA_H #define GRAPHELEMENTDATA_H diff --git a/src/data/graphelementproperty.h b/src/data/graphelementproperty.h index 4ebe104..5777c18 100644 --- a/src/data/graphelementproperty.h +++ b/src/data/graphelementproperty.h @@ -16,6 +16,11 @@ along with this program. If not, see . */ +/*! + * A class which holds either a single key/value pair (i.e. a proper property) + * or simply a key with no value (i.e. an atom). + */ + #ifndef GRAPHELEMENTPROPERTY_H #define GRAPHELEMENTPROPERTY_H @@ -26,13 +31,19 @@ class GraphElementProperty public: GraphElementProperty(); - // full constructor GraphElementProperty(QString key, QString value, bool atom); - // construct a proper property + /*! + * \brief GraphElementProperty constructs a proper property with the given key/value + * \param key + * \param value + */ GraphElementProperty(QString key, QString value); - // construct an atom + /*! + * \brief GraphElementProperty constructs an atom with the given key + * \param key + */ GraphElementProperty(QString key); QString key() const; @@ -40,9 +51,29 @@ public: QString value() const; void setValue(const QString &value); bool atom() const; + + /*! + * \brief operator == returns true for atoms if the keys match and for properties + * if the keys and values match. Note a property is never equal to an atom. + * \param p + * \return + */ bool operator==(const GraphElementProperty &p); + /*! + * \brief tikzEscape prepares a property key or value for export to tikz code. If + * the property only contains numbers, letters, whitespace, or the characters (<,>,-) + * this method does nothing. Otherwise, wrap the property in curly braces. + * \param str + * \return + */ static QString tikzEscape(QString str); + + /*! + * \brief tikz escapes the key/value of a propery or atom and outputs it as "key=value" + * for properties and "key" for atoms. + * \return + */ QString tikz(); signals: diff --git a/src/gui/exportdialog.h b/src/gui/exportdialog.h index 0f6940b..bcb6879 100644 --- a/src/gui/exportdialog.h +++ b/src/gui/exportdialog.h @@ -16,6 +16,10 @@ along with this program. If not, see . */ +/*! + * A dialog for exporting a LaTeX-generated preview to PNG, JPG, or PDF. + */ + #ifndef EXPORTDIALOG_H #define EXPORTDIALOG_H diff --git a/src/gui/latexprocess.h b/src/gui/latexprocess.h index 4fe9987..9853883 100644 --- a/src/gui/latexprocess.h +++ b/src/gui/latexprocess.h @@ -16,6 +16,11 @@ along with this program. If not, see . */ +/*! + * Run pdflatex and dump its output to the appropriate tab of + * the PreviewWindow. + */ + #ifndef LATEXPROCESS_H #define LATEXPROCESS_H diff --git a/src/gui/previewwindow.h b/src/gui/previewwindow.h index cf2ffd8..a14303b 100644 --- a/src/gui/previewwindow.h +++ b/src/gui/previewwindow.h @@ -16,6 +16,11 @@ along with this program. If not, see . */ +/*! + * Displays a LaTeX-generated PDF preview using Poppler. The right-click + * menu has options for exporting to file or clipboard. + */ + #ifndef PREVIEWWINDOW_H #define PREVIEWWINDOW_H diff --git a/src/gui/styleeditor.h b/src/gui/styleeditor.h index e9a8a89..2c35d56 100644 --- a/src/gui/styleeditor.h +++ b/src/gui/styleeditor.h @@ -16,6 +16,10 @@ along with this program. If not, see . */ +/*! + * A GUI editor for .tikzstyles files. + */ + #ifndef STYLEEDITOR_H #define STYLEEDITOR_H @@ -35,8 +39,8 @@ class StyleEditor : public QMainWindow Q_OBJECT public: - explicit StyleEditor(QWidget *parent = 0); - ~StyleEditor(); + explicit StyleEditor(QWidget *parent = nullptr); + ~StyleEditor() override; void open(); void save(); -- cgit v1.2.3