added some documentation to the source code

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 <https://www.gnu.org/licenses/>.

 */

 

+/*!

+ * 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<Node *, Node *> *nodeTable = 0);

+    explicit Edge(Node *s, Node *t, QObject *parent = nullptr);

+    Edge *copy(QMap<Node *, Node *> *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 <https://www.gnu.org/licenses/>.

 */

 

+/*!

+ * 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 <https://www.gnu.org/licenses/>.

 */

 

+/*!

+ * 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 <https://www.gnu.org/licenses/>.
 */
 
+/*!
+ * 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 <https://www.gnu.org/licenses/>.
 */
 
+/*!
+ * 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 <https://www.gnu.org/licenses/>.
 */
 
+/*!
+ * 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 <https://www.gnu.org/licenses/>.
 */
 
+/*!
+ * 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();