add comments

include/pierc/pierc.h

@@ -5,16 +5,22 @@
 #include <QFont>
 
 namespace pierc {
+    /* a special type of parser, only used to parse .pierc */
     typedef peg_parser::ParserGenerator<std::string> ConfigParser;
 
+    /* store the name of the font */
     extern std::string fontName;
+
+    /* store the size of the font */
     extern int fontSize;
 
+    /* configure the parser after initialization */
     void config(ConfigParser &parser);
 
-    // can use only once at the beginning when pie starts execution
+    /* used only once at the beginning when pie starts its execution */
     void gatherInfo();
 
+    /* retrieve the font family in format of *QFont* */
     QFont getFont();
 }// namespace pierc
 

include/shl/builtin.h

@@ -19,12 +19,14 @@
 using Attr = Style;
 
 namespace shl {
+    /* types of languages under syntax highlighting support */
     enum class LanguageType {
         CPP,
         JAVA,
         PYTHON,
     };
 
+    /* a pair of syntax highlighting message, including indexes and corresponding style attributes */
     class SyntaxHighlightInfo {
       public:
         mutable int idx = 0;
@@ -33,51 +35,65 @@ namespace shl {
         explicit SyntaxHighlightInfo(int idx, Attr attr);
     };
 
+    /* act as the return type of each semantic action */
     typedef std::vector<SyntaxHighlightInfo> SyntaxHighlightInfos;
     using Parser = peg_parser::ParserGenerator<std::string>;
     using ParserBuilder = peg_parser::ParserGenerator<std::shared_ptr<SyntaxHighlightInfos>, Parser &>;
 
     class Colors {
       private:
-        // not wise to use *unordered_set* here, try *unordered_map*
+        /* map color names to corresponding QFont objects */
         std::unordered_map<std::string, QColor> colors;
 
       public:
-        // get expression for PEG parser grammar
+        // get expression in parsing expression grammar
         std::string getExpr();
-        // hope all string in `colors` are lowercase
+        // all strings in `colors` are expected to be lowercase
         void append(const std::string &color, const QColor &_color);
         bool exist(const std::string &str);
         QColor get(const std::string &str);
     };
 
+    /* return a ParserBuilder that have finished configuration */
     ParserBuilder *generateParserBuilder(Colors &colors, Rope *);
 
+    /* check all colors under support */
     Colors getPredefinedColors();
 
+    /* receive path of shl file, return a parser generated according to the grammar of shl file */
     std::pair<bool, Parser> generateParserFromSHL(const std::string &filename, Rope *rope);
 
+    /* the initial configuration to a new ParserBuilder */
     void initParserBuilder(ParserBuilder &g, Colors &colors, Rope *, bool render = false);
 
-    extern std::vector<int> indentDepth;
-
-    extern std::vector<std::pair<int, int>> blockRecords;
+    /* debug messages when indent-aware feature is enable */
+    extern std::vector<int> indentDepth; // elements are the number of spaces as indent
+    extern std::vector<std::pair<int, int>> blockRecords; // record the beginning and the end line of an indent block
 
+    /* teach a ParserBuilder about the grammar of Syntax Highlighting Language */
     void initSHLGrammar(ParserBuilder &g);
 
+    /* find out the positional interval in text, from which line to which line */
     std::pair<long, long> getLineNumber(std::string_view input, std::pair<int, int> blockRecord);
 
+    /* return the real index described in shl language, given the size */
     int getIdx(const std::string &str, int size);
 
+    /* check if all the letters in the string are lowercase */
     bool isLowercase(const std::string &str);
 
+    /* generate the corresponding language parser */
+    /* user can directly invoke this API to get the final parser */
     std::pair<bool, shl::Parser> generateLanguageParser(LanguageType languageType, Rope *);
 }// namespace shl
 
+/* FilePath is designed to make file path experience consistent across Windows and Linux,
+ * without hardcoding the whole path */
 class FilePath {
   private:
     std::string pathString; // stores the actual path on different system
 
+    /* get separator, determined in runtime */
     const static char _separator = 
 #if defined _WIN32 || defined __CYGWIN__
       '\\';
@@ -86,10 +102,12 @@ class FilePath {
 #endif
 
   public:
+    /* allow multiple strings as arguments */
     explicit FilePath(int n_args, ...);
 
     ~FilePath() = default;
 
+    /* reconstruct the path if the path needs to modifying */
     static std::string constructFileString(int n_args, ...);
 
     std::string getPathString() const;

include/ui/actions.hpp

@@ -3,24 +3,42 @@
 #include "libs.hpp"
 #include "rope.hpp"
 
+/* primitive text objects that indicate some part of certain text */
 enum PrimitveObject {
+    /* current selected text */
     Selection,
+    /* NextH(PrevH) the char on the right(left) of current cursor */
     NextH, PrevH,
+    /* NextV(PrevV) the char on the bottom(top) of current cursor */
     NextV, PrevV,
+    /* NextW(PrevW) the word on the right(left) of current cursor */
     NextW, PrevW,
+    /* The whole line(s) containing current selection */
     CurLine,
+    /* Current line, or the next one if current one is already
+     * fully selected */
     Line,
+    /* Begin/End of the line containing current cursor */
     LineBeg, LineEnd,
+    /* The region between a char and its matching one,
+     * for example '(' and ')', '[' and ']' */
     Match
 };
 
+/* An object of some derived class of [ActionVisitor] is something
+ * capable to perform all allowed actions */
 class ActionVisitor {
 public:
+    /* Return the interval corresponding to the text object */
     virtual Interval getObject(PrimitveObject) = 0;
 
+    /* insert a character before current cursor position */
     virtual void insertChar(QChar c) = 0;
+    /* set the selection to be the given interval */
     virtual void setSelection(Interval) = 0;
+    /* expand the selection so that it contains the given interval */
     virtual void expandSelection(Interval) = 0;
+    /* delete an interval from the text */
     virtual void delInterval(Interval) = 0;
 
     virtual void pushCount(int digit) = 0;
@@ -32,13 +50,16 @@ class ActionVisitor {
 };
 
 
+/* An abstract base class for all possible actions.
+ * Using the Visitor Model to implement */
 class Action {
 public:
     virtual void accept(ActionVisitor *) = 0;
-    virtual ~Action() {};
+    virtual ~Action() = default;
 };
 
 
+/* The action that modifies current selection */
 class ModifySelection: public Action {
 public:
     ModifySelection(bool expand, PrimitveObject);
@@ -51,7 +72,7 @@ class ModifySelection: public Action {
     PrimitveObject m_obj;
 };
 
-
+/* The action that insert a single char */
 class InsertChar : public Action {
 public:
     InsertChar(QChar c);
@@ -62,21 +83,26 @@ class InsertChar : public Action {
     QChar m_char;
 };
 
+/* The action that deletes the char before current cursor */
 class Backspace : public Action {
 public:
     void accept(ActionVisitor *) override;
 };
 
+/* The action that inserts a newline at the end of current line,
+ * and enter "insert" mode */
 class InsertNewline : public Action {
 public:
     void accept(ActionVisitor *) override;
 };
 
+/* The action that deletes current selection */
 class DelSelection : public Action {
 public:
     void accept(ActionVisitor *) override;
 };
 
+/* The action that deletes current selection and enters insert mode */
 class ReplaceSelection : public Action {
 public:
     void accept(ActionVisitor *) override;
@@ -91,16 +117,19 @@ class PushCountChar : public Action {
     int m_count;
 };
 
+/* The action that undo the last operation */
 class Undo : public Action {
 public:
     void accept(ActionVisitor *) override;
 };
 
+/* The action that redo the last undone operation */
 class Redo : public Action {
 public:
     void accept(ActionVisitor *) override;
 };
 
+/* The action that switch current mode */
 class SetMode : public Action {
 public:
     SetMode(QString);

include/ui/config.hpp

@@ -1,16 +1,28 @@
 #pragma once
 
+
+/* This file contains possible settings of pie */
 #include "libs.hpp"
 
+/* The [Style] type records how a character should be
+ * displayed. */
 struct Style {
+    /* foreground and background color */
     QColor fg, bg;
+    /* whether the character should be bold/italic */
     bool bold, italic;
+    /* underline: a line is drawn on the bottom of the character
+     * strikethrough: a line is drawn on the middle of the character */
     bool underline, strikethrough;
 
     bool operator==(const Style &) const;
     bool operator!=(const Style &) const;
 
+    /* Builtin styles used by pie internally */
+    /* default style for characters */
     static Style default_style;
+    /* the style for the cursor */
     static Style cursor_style;
+    /* the style for selected chars other than the cursor */
     static Style selection_style;
 };

include/ui/libs.hpp

@@ -1,5 +1,6 @@
 #pragma once
 
+/* This file contains the necessary external dependencies */
 #include <cstring>
 #include <cassert>
 #include <stack>

include/ui/modes.hpp

@@ -3,23 +3,34 @@
 #include "libs.hpp"
 #include "actions.hpp"
 
+/* An object of [Mode] represents a text editing mode
+ * that has a series of key bindings */
 class Mode {
 public:
     Mode(QString name);
     ~Mode();
 
     const QString &name();
 
+    /* Add a new key binding to a mode */
     void addBinding(Qt::KeyboardModifiers mods, int key, Action *);
+    /* Accept a [QKeyEvent], and executes corresponding actions
+     * on the visitor if the event matches any of the mode's key bindings */
     void acceptKeyEvent(QKeyEvent *, ActionVisitor *);
 
 public:
+    /* Find a mode (globally) by its name.
+     * Return [nullptr] if not found */
     static Mode *findMode(const QString &);
+    /* Init default modes and their key bindings */
     static void initDefaultModes();
+    /* Builtin "normal" mode */
     static Mode normal;
+    /* Builtin "insert" mode */
     static Mode insert;
 
 private:
+    /* All defined modes */
     static QMap<QString, Mode*> all_modes;
 
 private: