From 2c9bdb0305bad2ea59b6be6db6bbf38d581d4a28 Mon Sep 17 00:00:00 2001
From: Maurizio Monge <maurizio@localhost.localdomain>
Date: Thu, 12 Jul 2007 15:20:03 +0200
Subject: [PATCH] Improved documentation of the Index class

---
 src/index.cpp | 14 +-------------
 src/index.h   | 23 +++++++++++++++++++++++
 2 files changed, 24 insertions(+), 13 deletions(-)

diff --git a/src/index.cpp b/src/index.cpp
index 5352b72..f9ee3f0 100644
--- a/src/index.cpp
+++ b/src/index.cpp
@@ -36,7 +36,6 @@ Index Index::fromString(const QString& s) {
   return retv;
 }
 
-/** returns the number of moves from the start of the game */
 int Index::totalNumMoves() const {
   int retv = num_moves;
 
@@ -46,16 +45,13 @@ int Index::totalNumMoves() const {
   return retv;
 }
 
-/** true if this index is the first of a variation branch */
 bool Index::atVariationStart() const {
   return nested.size() && (nested[nested.size()-1].num_moves == 0);
 }
 
-/** flip variation */
 Index Index::flipVariation(const Index& vstart, int v_id) const {
   int s = vstart.nested.size();
-  if(s)
-  {
+  if(s) {
     if( (int)nested.size() < s
         || vstart.num_moves != num_moves)
       return *this;
@@ -108,9 +104,6 @@ Index Index::flipVariation(const Index& vstart, int v_id) const {
     return *this;
 }
 
-/** Returns an index the point to the next position. If variation is != -1, you will be entering in the
-    sub-variation with this id instead of continuing in the current main line. You can also specify
-    the number of moves you want to go on (in the main line or in the specified variation) */
 Index Index::next(int variation_id, int num) const {
   Index retv = *this;
   if(variation_id != -1)
@@ -123,7 +116,6 @@ Index Index::next(int variation_id, int num) const {
   return retv;
 }
 
-/** Returns an index pointing to the previous position (or to a position n moves back)  */
 Index Index::prev(int _num) const {
   int num = _num;
   Index retv = *this;
@@ -153,8 +145,6 @@ Index Index::prev(int _num) const {
   return retv;
 }
 
-/** Returns an index that is the minimum of this index and the given one, ie the branch point
-    of the lines from start to the two indices. */
 Index Index::min(const Index& ix) const  {
   if(ix.num_moves != num_moves)
     return Index( std::min(ix.num_moves, num_moves) );
@@ -172,7 +162,6 @@ Index Index::min(const Index& ix) const  {
   return retv;
 }
 
-/** Returns the number of steps down and up you have to do to go from this index to the given one */
 std::pair<int, int> Index::stepsTo(const Index& ix) const {
   int i;
   int down = 0, up = 0;
@@ -204,7 +193,6 @@ std::pair<int, int> Index::stepsTo(const Index& ix) const {
   return std::pair<int,int>(down, up);
 }
 
-/** returns the number of moves in the most nested variation */
 int Index::lastIndex() {
   return nested.size() ? nested[nested.size()-1].num_moves : num_moves;
 }
diff --git a/src/index.h b/src/index.h
index 5b76132..6efdd53 100644
--- a/src/index.h
+++ b/src/index.h
@@ -43,14 +43,36 @@ public:
       is the number of moves played in the main line */
   Index(int n) : num_moves(n) {}
 
+  /** return a string like "1_2.3_4.5" */
   operator QString() const;
+
+  /** returns the number of moves from the start of the game */
   int totalNumMoves() const;
+
+  /** \return true if this index is the first of a variation branch */
   bool atVariationStart() const;
+
+  /** flip variation: returns the current index changed as if it was in the subvariation \a vid
+      at \a vstart instead of mainline and viceversa, ie at \a vstart the mainline becames
+      subvariation \a vid and viceversa */
   Index flipVariation(const Index& vstart, int v_id) const;
+
+  /** Returns an index the point to the next position. If variation is != -1, you will be entering in the
+    sub-variation with this id instead of continuing in the current main line. You can also specify
+    the number of moves you want to go on (in the main line or in the specified variation) */
   Index next(int variation_id = -1, int num = 1) const;
+
+  /** Returns an index pointing to the previous position (or to a position n moves back)  */
   Index prev(int _num = 1) const;
+
+  /** Returns an index that is the minimum of this index and the given one, ie the branch point
+    of the lines from start to the two indices. */
   Index min(const Index& ix) const;
+
+  /** Returns the number of steps down and up you have to do to go from this index to the given one */
   std::pair<int, int> stepsTo(const Index& ix) const;
+
+  /** returns the number of moves in the most nested variation */
   int lastIndex();
 
   /** True if this index refers to a position 'before' than the given one */
@@ -86,6 +108,7 @@ public:
     return !(*this == ix);
   }
 
+  /** \return an index from a string like "1_2.3_4.5" */
   static Index fromString(const QString& s);
 };
 
-- 
2.11.4.GIT