commit 3b6232679d201b78de40e60e2d312fd281b29e30
Author: Georg Baum <[email protected]>
Date: Wed Mar 18 21:31:50 2015 +0100
Improve source code documentation
Adjust comments to current code and extend them a bit, also revert a part
of af5acb6d which was certainly not wanted.
diff --git a/src/CursorSlice.h b/src/CursorSlice.h
index fa7af6a..f44c92e 100644
--- a/src/CursorSlice.h
+++ b/src/CursorSlice.h
@@ -32,7 +32,7 @@ class Paragraph;
/// This encapsulates a single slice of a document iterator as used e.g.
/// for cursors.
-// After IU, the distinction of MathInset and InsetOld as well as
+// After inset unification, the distinction of InsetMath and Inset as well as
// that of MathData and Text should vanish. They are conceptually the
// same (now...)
@@ -89,7 +89,11 @@ public:
pos_type pos() const { return pos_; }
/// return the position within the paragraph
pos_type & pos() { return pos_; }
- /// return the last position within the paragraph
+ /*!
+ * \return the last position within the paragraph.
+ * Note that this is the position behind the last character or inset,
+ * i.e. you cannot dereference it.
+ */
pos_type lastpos() const;
/// return the number of embedded cells
size_t nargs() const { return inset_->nargs(); }
@@ -152,7 +156,9 @@ private:
* Cell index of a position in this inset.
* This is the primary cell information also for grid like insets,
* although we have the convenience functions row() and col() for
- * those * and column changes every time the number of columns ornumber
+ * those.
+ * This means that the corresponding idx_ of a cell in a given row
+ * and column changes every time the number of columns or number
* of rows changes. Normally the cursor should stay in the same cell,
* so these changes should typically be performed like the following:
* \code
diff --git a/src/support/types.h b/src/support/types.h
index 0e25333..fc443dc 100644
--- a/src/support/types.h
+++ b/src/support/types.h
@@ -20,12 +20,21 @@
namespace lyx {
- /// a type for positions used in paragraphs
- // needs to be signed for a while to hold the special value -1 that is
- // used there
+ /*!
+ * A type for positions used in paragraphs.
+ * Each position is either occupied by a single character or an inset.
+ * For insets, the placeholder META_INSET is stored in the paragraph
+ * text, and the actual insets are maintained separately.
+ */
+ // FIXME: should be unsigned, but needs to be signed for a while to
+ // hold the special value -1 that is used somewhere
+ // Note that the signed property is also used in loops counting to zero.
typedef ptrdiff_t pos_type;
- /// a type for paragraph offsets
+ /*!
+ * A type for paragraph offsets.
+ * This is used to address paragraphs in ParagraphList, Text etc.
+ */
// FIXME: should be unsigned as well.
// however, simply changing it breaks a downward loop somewhere...
typedef ptrdiff_t pit_type;
@@ -47,13 +56,13 @@ namespace lyx {
struct size_type {
///
- typedef size_t base_type;
+ typedef size_t base_type;
///
size_type(base_type t) { data_ = t; }
///
operator base_type() const { return data_; }
///
- private:
+ private:
base_type data_;
};
@@ -61,8 +70,8 @@ namespace lyx {
///
enum word_location {
- // the word around the cursor, only if the cursor is
- //not at a boundary
+ /// the word around the cursor, only if the cursor is
+ /// not at a boundary
WHOLE_WORD_STRICT,
// the word around the cursor
WHOLE_WORD,
