From: Georg Baum <baum@lyx.org>
Date: Wed, 18 Mar 2015 20:31:50 +0000 (+0100)
Subject: Improve source code documentation
X-Git-Tag: 2.2.0alpha1~1137
X-Git-Url: https://git.lyx.org/gitweb/?a=commitdiff_plain;h=3b6232679d201b78de40e60e2d312fd281b29e30;p=features.git

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 fa7af6ad17..f44c92e0c2 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 0e25333672..fc443dcf53 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,