Description of CBot instructions

src/CBot/CBotDebug.h

@@ -23,9 +23,16 @@ namespace CBot
 {
 class CBotProgram;
 
+/**
+ * \brief Various utilities used for debugging
+ */
 class CBotDebug
 {
 public:
+    /**
+     * \brief Dump the compiled class structure of the given program to stdout as DOT graph
+     * \param program Program to dump
+     */
     static void DumpCompiledProgram(CBotProgram* program);
 };
 

src/CBot/CBotInstr/CBotBlock.h

@@ -24,15 +24,19 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotBlock class An instruction block { .... }.
+ * \brief An instruction block - { ... }
+ *
+ * There is never an instance of this class - it gets compiled into CBotListInstr
+ *
+ * \see CBotListInstr
  */
 class CBotBlock : public CBotInstr
 {
 public:
 
-    /*!
+    /**
-     * \brief Compile Compiles a statement block " { i ; i ; } "
+     * \brief Compiles a statement block - { instr; instr; }
      * \param p
      * \param pStack
      * \param bLocal
@@ -40,8 +44,8 @@ public:
      */
     static CBotInstr* Compile(CBotToken* &p, CBotCStack* pStack, bool bLocal = true);
 
-    /*!
+    /**
-     * \brief CompileBlkOrInst
+     * \brief Compiles a block of instructions or a single instruction
      * \param p
      * \param pStack
      * \param bLocal
@@ -50,14 +54,8 @@ public:
     static CBotInstr* CompileBlkOrInst(CBotToken* &p, CBotCStack* pStack, bool bLocal = false);
 
 private:
-
-    /*!
-     * \brief CBotBlock This class have no constructor because there is never an
-     * instance of this class the object returned by Compile is usually of type
-     * CBotListInstr
-     */
     CBotBlock() = delete;
-    CBotBlock(const CBotBlock &) = delete;
+    CBotBlock(const CBotBlock&) = delete;
 };
 
 } // namespace CBot

src/CBot/CBotInstr/CBotBoolExpr.h

@@ -24,11 +24,12 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotBoolExpr class Compile a statement such as "(condition)"
+ * \brief An expression that results in a boolean value
- * the condition must be Boolean. This class has no constructor, because there
+ *
- * is never an instance of this class the object returned by Compile is usually
+ * There is never an instance of this class - it gets compiled into CBotExpression
- * type CBotExpression
+ *
+ * \see CBotExpression
  */
 class CBotBoolExpr : public CBotInstr
 {
@@ -41,6 +42,10 @@ public:
      * \return
      */
     static CBotInstr* Compile(CBotToken* &p, CBotCStack* pStack);
+
+private:
+    CBotBoolExpr() = delete;
+    CBotBoolExpr(const CBotBoolExpr&) = delete;
 };
 
 } // namespace CBot

src/CBot/CBotInstr/CBotBoolean.h

@@ -24,21 +24,13 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotBoolean class Defining a boolean variable int a, b = false;
+ * \brief Definition of boolean variable - bool a, b = false
  */
 class CBotBoolean : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotBoolean
-     */
     CBotBoolean();
-
-    /*!
-     * \brief ~CBotBoolean
-     */
     ~CBotBoolean();
 
     /*!

src/CBot/CBotInstr/CBotBreak.h

@@ -24,22 +24,14 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotBreak class Compiles instruction "break" or "continu".
+ * \brief Instructions "break" and "continue" (with an optional label)
  */
 class CBotBreak : public CBotInstr
 {
 
 public:
-
-    /*!
-     * \brief CBotBreak
-     */
     CBotBreak();
-
-    /*!
-     * \brief CBotBreak
-     */
     ~CBotBreak();
 
     /*!

src/CBot/CBotInstr/CBotCase.h

@@ -24,23 +24,16 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotCase class Compiles instruction "case" we are bound to the
+ * \brief Instruction "case", part of "switch" structure
- * statement block "switch".
+ *
+ * \see CBotSwitch
  */
 class CBotCase : public CBotInstr
 {
 
 public:
-
-    /*!
-     * \brief CBotCase
-     */
     CBotCase();
-
-    /*!
-     * \brief ~CBotCase
-     */
     ~CBotCase();
 
     /*!

src/CBot/CBotInstr/CBotCatch.h

@@ -25,20 +25,14 @@ namespace CBot
 {
 
 /*!
- * \brief The CBotCatch class. Compiles instruction "catch".
+ * \brief Instruction "catch", part of "try" structure
+ *
+ * \see CBotTry
  */
 class CBotCatch : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotCatch
-     */
     CBotCatch();
-
-    /*!
-     * \brief CBotCatch
-     */
     ~CBotCatch();
 
     /*!

src/CBot/CBotInstr/CBotClassInst.h

@@ -24,22 +24,24 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotClassInst class Definition of an element of any class.
+ * \brief Definition of class instance variable
+ *
+ * Examples:
+ * \code
+ * ClassName varname;
+ * ClassName varname();
+ * ClassName varname = new ClassName();
+ * ClassName varname = new ClassName(args);
+ * ClassName varname1(), varname2();
+ * ClassName varname1 = new ClassName(), varname2;
+ * \endcode
  */
 class CBotClassInst : public CBotInstr
 {
 
 public:
-
-    /*!
-     * \brief CBotClassInst
-     */
     CBotClassInst();
-
-    /*!
-     * \brief ~CBotClassInst
-     */
     ~CBotClassInst();
 
     /*!

src/CBot/CBotInstr/CBotCondition.h

@@ -24,10 +24,13 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotCondition class This class has no constructor, because there
+ * \brief A condition - boolean expression enclosed in brackets - (condition)
- * is never an instance of this class the object returned by Compile is usually
+ *
- * type CBotExpression
+ * There is never an instance of this class - it gets compiled into CBotExpression
+ *
+ * \see CBotBoolExpr
+ * \see CBotExpression
  */
 class CBotCondition : public CBotInstr
 {
@@ -41,6 +44,10 @@ public:
      * \return
      */
     static CBotInstr* Compile(CBotToken* &p, CBotCStack* pStack);
+
+private:
+    CBotCondition() = delete;
+    CBotCondition(const CBotCondition&) = delete;
 };
 
 } // namespace CBot

src/CBot/CBotInstr/CBotDo.h

@@ -24,18 +24,13 @@
 namespace CBot
 {
 
+/**
+ * \brief do {...} while (...) structure
+ */
 class CBotDo : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotDo Default constructor.
-     */
     CBotDo();
-
-    /*!
-     * \brief ~CBotDo Destructor.
-     */
     ~CBotDo();
 
     /*!

src/CBot/CBotInstr/CBotEmpty.h

@@ -24,8 +24,9 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotEmpty class
+ * \brief Constant -1 of type int
+ * \todo Whaaaat? What is this even doing here? ~krzys_h
  */
 class CBotEmpty : public CBotInstr
 {

src/CBot/CBotInstr/CBotExprAlpha.h

@@ -24,21 +24,13 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotExprAlpha class Expression representing a string.
+ * \brief Expression representing a string literal - "Some text"
  */
 class CBotExprAlpha : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotExprAlpha
-     */
     CBotExprAlpha();
-
-    /*!
-     * \brief CBotExprAlpha
-     */
     ~CBotExprAlpha();
 
     /*!

src/CBot/CBotInstr/CBotExprBool.h

@@ -24,21 +24,13 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotExprBool class Compile a token representing true or false.
+ * \brief true/false constants
  */
 class CBotExprBool : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotExprBool
-     */
     CBotExprBool();
-
-    /*!
-     * \brief ~CBotExprBool
-     */
     ~CBotExprBool();
 
     /*!

src/CBot/CBotInstr/CBotExprNan.h

@@ -24,21 +24,13 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotExprNan class Management of the operand "nan".
+ * \brief The "nan" constant
  */
 class CBotExprNan : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotExprNan
-     */
     CBotExprNan();
-
-    /*!
-     * \brief ~CBotExprNan
-     */
     ~CBotExprNan();
 
     /*!

src/CBot/CBotInstr/CBotExprNull.h

@@ -24,21 +24,13 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotExprNull class Management of the operand "null".
+ * \brief The "null" constant
  */
 class CBotExprNull : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotExprNull
-     */
     CBotExprNull();
-
-    /*!
-     * \brief ~CBotExprNull
-     */
     ~CBotExprNull();
 
     /*!

src/CBot/CBotInstr/CBotExprNum.h

@@ -24,22 +24,16 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotExprNum class Expression representing a number.
+ * \brief A number literal - 5, 1, 2.5, 3.75, etc. or a predefined numerical constant (see CBotToken::DefineNum())
+ *
+ * Can be of type ::CBotTypInt or ::CBotTypFloat
  */
 class CBotExprNum : public CBotInstr
 {
 
 public:
-
-    /*!
-     * \brief CBotExprNum
-     */
     CBotExprNum();
-
-    /*!
-     * \brief ~CBotExprNum
-     */
     ~CBotExprNum();
 
     /*!

src/CBot/CBotInstr/CBotExprUnaire.h

@@ -24,22 +24,13 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotExprUnaire class Unary expression. Compile an unary expression
+ * \brief Unary expression - +a, -a, !a, ~a, not a
- * eg : (+, * -, not, !, ~)
  */
 class CBotExprUnaire : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotExprUnaire
-     */
     CBotExprUnaire();
-
-    /*!
-     * \brief ~CBotExprUnaire
-     */
     ~CBotExprUnaire();
 
     /*!

src/CBot/CBotInstr/CBotExprVar.h

@@ -27,22 +27,16 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotExprVar class Expression for the variable name. Compile a
+ * \brief Expression representing a variable name
- * variable name check that it is known on the stack and it has been initialized.
+ *
+ * Verifies that variable is known during compilation
+ * Verifies taht variable is initialized during execution
  */
 class CBotExprVar : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotExprVar
-     */
     CBotExprVar();
-
-    /*!
-     * \brief ~CBotExprVar
-     */
     ~CBotExprVar();
 
     /*!

src/CBot/CBotInstr/CBotExpression.h

@@ -26,32 +26,22 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotExpression class Compiles a statement with or without
+ * \brief An arithmetic expression, with or without assignment
- * assignment.
+ *
- * eg :
+ * Examples:
- *     - x = a;
+ * \code
- *     - x * y + 3;
+ * x = a
- *     - x = 123
+ * x * y + 3
- *     - z * 5 + 4
+ * x = 123
+ * z * 5 + 4
+ * \endcode
  */
 
-
-// compiles a statement such as "  " ou " z * 5 + 4 "
-//
-
 class CBotExpression : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotExpression
-     */
     CBotExpression();
-
-    /*!
-     * \brief ~CBotExpression
-     */
     ~CBotExpression();
 
     /*!

src/CBot/CBotInstr/CBotFieldExpr.h

@@ -24,22 +24,13 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotFieldExpr class Management of the fields of an instance
+ * \brief Accessing a class field using dot operator - toto.x
- * (dot operator) eg : toto.x
  */
 class CBotFieldExpr : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotFieldExpr
-     */
     CBotFieldExpr();
-
-    /*!
-     * \brief ~CBotFieldExpr
-     */
     ~CBotFieldExpr();
 
     /*!

src/CBot/CBotInstr/CBotFloat.h

@@ -24,8 +24,8 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotFloat class Definition of a real/float variable int a, b = 12.4;
+ * \brief Definition of a float variable - float a, b = 12.4
  */
 class CBotFloat : public CBotInstr
 {

src/CBot/CBotInstr/CBotFor.h

@@ -24,21 +24,13 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotFor class
+ * \brief Instruction for (init; test; incr) { ... }
  */
 class CBotFor : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotFor
-     */
     CBotFor();
-
-    /*!
-     * \brief CBotFor
-     */
     ~CBotFor();
 
     /*!

src/CBot/CBotInstr/CBotFunction.h

@@ -26,22 +26,23 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotFunction class A function declaration. Compilation of various
+ * \brief A function declaration in the code
- * functions declared by the user
+ *
+ * Examples:
+ * \code
+ * void test() { ... }
+ * void test(int a, float b) { ... }
+ * int test(int a, float b, string c) { ... }
+ * public bool test(int a, float b, string c, SomeClass d) { ... }
+ * extern void test() { ... }
+ * void classname::test() { ... }
+ * \endcode
  */
 class CBotFunction : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotFunction
-     */
     CBotFunction();
-
-    /*!
-     * \brief ~CBotFunction
-     */
     ~CBotFunction();
 
     /*!

src/CBot/CBotInstr/CBotIString.h

@@ -24,8 +24,8 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotIString class Define a string variable eg : int a, b = "salut";
+ * \brief Definition of a string variable - string a, b = "text";
  */
 class CBotIString : public CBotInstr
 {

src/CBot/CBotInstr/CBotIf.h

@@ -24,21 +24,13 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotIf class Instruction if (condition) operation1 else operation2;
+ * \brief Instruction if (condition) { ... } else { ... }
  */
 class CBotIf : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotIf
-     */
     CBotIf();
-
-    /*!
-     * \brief ~CBotIf
-     */
     ~CBotIf();
 
     /*!

src/CBot/CBotInstr/CBotIndexExpr.h

@@ -24,23 +24,13 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotIndexExpr class Index management for arrays
+ * \brief Instruction accessing an array element - array[x]
- * eg :
- *     - array [ expression ]
  */
 class CBotIndexExpr : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotIndexExpr
-     */
     CBotIndexExpr();
-
-    /*!
-     * \brief ~CBotIndexExpr
-     */
     ~CBotIndexExpr();
 
     /*!

src/CBot/CBotInstr/CBotInstArray.h

@@ -24,24 +24,20 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotInstArray class Definition of an array.
+ * \brief Definition of an array (of any type)
- * Defining an array of any type
+ *
+ * Examples:
+ * \code
  * int a[12];
- * point x[];
+ * float x[];
+ * bool[] z;
+ * \endcode
  */
 class CBotInstArray : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotInstArray
-     */
     CBotInstArray();
-
-    /*!
-     * \brief ~CBotInstArray
-     */
     ~CBotInstArray();
 
     /*!
@@ -68,7 +64,7 @@ public:
     void RestoreState(CBotStack* &pj, bool bMain) override;
 
 protected:
-    virtual const std::string GetDebugName() { return "CBotInstrArray"; }
+    virtual const std::string GetDebugName() { return "CBotInstArray"; }
     virtual std::string GetDebugData();
     virtual std::map<std::string, CBotInstr*> GetDebugLinks();
 

src/CBot/CBotInstr/CBotInstr.h

@@ -28,26 +28,59 @@ namespace CBot
 {
 class CBotDebug;
 
-/*
-    for example, the following program
-    int        x[]; x[1] = 4;
-    int        y[x[1]][10], z;
-    is generated
-    CBotInstrArray
-    m_next3b-> CBotEmpty
-    m_next->
-    CBotExpression ....
-    m_next->
-    CBotInstrArray
-    m_next3b-> CBotExpression ('x') ( m_next3-> CBotIndexExpr ('1') )
-    m_next3b-> CBotExpression ('10')
-    m_next2-> 'z'
-    m_next->...
-
-*/
 /**
  * \brief Class for one CBot instruction
  *
+ * For example, for program:
+ * \code
+ * int x[]; x[1] = 4;
+ * int y[x[1]][10], z;
+ * \endcode
+ * the following structure is generated:
+ * \dot
+ * # Generated using the CBot_compile_graph tool
+ * # and slightly modified
+ * digraph {
+ * start [label=<START> shape=box3d color=cyan]
+ * instr00000000015304D0 [label=<<b>CBotInstrArray</b><br/>int[]>]
+ * instr0000000001530870 [label=<<b>CBotExpression</b>>]
+ * instr0000000001530920 [label=<<b>CBotLeftExpr</b><br/>x>]
+ * instr00000000015309D0 [label=<<b>CBotIndexExpr</b>>]
+ * instr0000000001530DC0 [label=<<b>CBotExprNum</b><br/>(int) 1>]
+ * instr00000000015309D0 -> instr0000000001530DC0 [label="m_expr" weight=5]
+ * instr0000000001530920 -> instr00000000015309D0 [label="m_next3" weight=5]
+ * instr0000000001530870 -> instr0000000001530920 [label="m_leftop" weight=5]
+ * instr0000000001530E80 [label=<<b>CBotInstrArray</b><br/>int[][]>]
+ * instr00000000015315F0 [label=<<b>CBotInt</b>>]
+ * instr0000000001531C20 [label=<<b>CBotLeftExprVar</b><br/>z>]
+ * instr00000000015315F0 -> instr0000000001531C20 [label="m_var" weight=5]
+ * instr0000000001530E80 -> instr00000000015315F0 [label="m_next2b" weight=5]
+ * { rank=same; instr0000000001530E80; instr00000000015315F0; }
+ * instr0000000001530B50 [label=<<b>CBotExprVar</b><br/>x>]
+ * instr0000000001531700 [label=<<b>CBotIndexExpr</b>>]
+ * instr0000000001531B60 [label=<<b>CBotExprNum</b><br/>(int) 1>]
+ * instr0000000001531700 -> instr0000000001531B60 [label="m_expr" weight=5]
+ * instr0000000001530B50 -> instr0000000001531700 [label="m_next3" weight=5]
+ * instr0000000001531A00 [label=<<b>CBotExprNum</b><br/>(int) 10>]
+ * instr0000000001530B50 -> instr0000000001531A00 [label="m_next3b" weight=5]
+ * instr0000000001530E80 -> instr0000000001530B50 [label="m_next3b" weight=5]
+ * instr0000000001530A80 [label=<<b>CBotLeftExprVar</b><br/>y>]
+ * instr0000000001530E80 -> instr0000000001530A80 [label="m_var" weight=5]
+ * instr0000000001530870 -> instr0000000001530E80 [label="m_next" weight=1]
+ * { rank=same; instr0000000001530870; instr0000000001530E80; }
+ * instr0000000001530C80 [label=<<b>CBotExprNum</b><br/>(int) 4>]
+ * instr0000000001530870 -> instr0000000001530C80 [label="m_rightop" weight=5]
+ * instr00000000015304D0 -> instr0000000001530870 [label="m_next" weight=1]
+ * { rank=same; instr00000000015304D0; instr0000000001530870; }
+ * instr0000000001530670 [label=<<b>CBotEmpty</b>>]
+ * instr00000000015304D0 -> instr0000000001530670 [label="m_next3b" weight=5]
+ * instr00000000015305A0 [label=<<b>CBotLeftExprVar</b><br/>x>]
+ * instr00000000015304D0 -> instr00000000015305A0 [label="m_var" weight=5]
+ * { rank=same; start; instr00000000015304D0; }
+ * start -> instr00000000015304D0
+ * }
+ * \enddot
+ *
  * \todo More documentation
  */
 class CBotInstr
@@ -250,12 +283,23 @@ public:
 
 protected:
     friend class CBotDebug;
+    /**
+     * \brief Returns the name of this class
+     * \see CBotDebug
+     */
     virtual const std::string GetDebugName() = 0;
+    /**
+     * \brief Returns additional data associated with this instruction for debugging purposes
+     * \see CBotDebug
+     */
     virtual std::string GetDebugData() { return ""; }
+    /**
+     * Returns a map of all instructions connected with this one
+     * \see CBotDebug
+     */
     virtual std::map<std::string, CBotInstr*> GetDebugLinks();
 
 protected:
-
     //! Keeps the token.
     CBotToken m_token;
     //! Linked command.

src/CBot/CBotInstr/CBotInstrCall.h

@@ -24,21 +24,15 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotInstrCall class Calls of these functions.
+ * \brief A call to a function - func()
+ *
+ * \see CBotInstrMethode for class methods
  */
 class CBotInstrCall : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotInstrCall
-     */
     CBotInstrCall();
-
-    /*!
-     * \brief ~CBotInstrCall
-     */
     ~CBotInstrCall();
 
     /*!

src/CBot/CBotInstr/CBotInstrMethode.h

@@ -24,21 +24,13 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotInstrMethode class A call of method. Compile a method call.
+ * \brief A call to class method - var.func()
  */
 class CBotInstrMethode : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotInstrMethode
-     */
     CBotInstrMethode();
-
-    /*!
-     * \brief ~CBotInstrMethode
-     */
     ~CBotInstrMethode();
 
     /*!

src/CBot/CBotInstr/CBotInt.h

@@ -24,22 +24,13 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotInt class Definition of an integer variable
+ * \brief Definition of an integer variable - int a, b = 12
- * int a, b = 12;
  */
 class CBotInt : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotInt
-     */
     CBotInt();
-
-    /*!
-     * \brief ~CBotInt
-     */
     ~CBotInt();
 
     /*!

src/CBot/CBotInstr/CBotLeftExpr.h

@@ -24,36 +24,29 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotLeftExpr class Accept the expressions that be to the left of
+ * \brief Compilation of left side of an assignment
- * assignment.
+ *
+ * Some examples:
+ * \code
+ * varname
+ * varname[3]
+ * varname.x
+ * varname.pos.x
+ * varname[2].pos.x
+ * varname[1].pos[2].x
+ * varname[1][2][3]
+ * \endcode
  */
 class CBotLeftExpr : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotLeftExpr
-     */
     CBotLeftExpr();
-
-    /*!
-     * \brief ~CBotLeftExpr
-     */
     ~CBotLeftExpr();
 
     /*!
      * \brief Compile Compiles an expression for a left-operand
      * (left of an assignment).
-     * eg :
-     *     - toto
-     *     - toto[ 3 ]
-     *     - toto.x
-     *     - toto.pos.x
-     *     - toto[2].pos.x
-     *     - toto[1].pos[2].x
-     *     - toto[1][2][3]
-     *
      * \param p
      * \param pStack
      * \return

src/CBot/CBotInstr/CBotLeftExprVar.h

@@ -25,7 +25,7 @@ namespace CBot
 {
 
 /**
- * \brief Expression on the left side of an assignment
+ * \brief A variable on the left side of an assignment
  */
 class CBotLeftExprVar : public CBotInstr
 {

src/CBot/CBotInstr/CBotListArray.h

@@ -24,23 +24,13 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotListArray class Definition of a assignment list for a table
+ * \brief Compilation of assignment of an array - {{1, 2, 3}, {3, 2, 1}}
- * int [ ] a [ ] = ( ( 1, 2, 3 ) , ( 3, 2, 1 ) ) ;
  */
 class CBotListArray : public CBotInstr
 {
-
 public:
-
-    /*!
-     * \brief CBotListArray
-     */
     CBotListArray();
-
-    /*!
-     * \brief ~CBotListArray
-     */
     ~CBotListArray();
 
     /*!

src/CBot/CBotInstr/CBotListExpression.h

@@ -24,22 +24,29 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotListExpression class. Compiles a list of expressions is used
+ * \brief Compile a comma-separated list of expressions or variable definitions
- * only in "for" statement in incrementing and intitialisation.
+ *
+ * Used by for() in initialization and increment statements
+ *
+ * Examples:
+ * \code
+ * int a
+ * a = 0
+ * a = 0, int b = 3
+ * a = 5, b = 7
+ * int a = 3, b = 8 // TODO: does that compile into declaration of two variables or declaration and assignment?
+ * i++
+ * i++, j++
+ * int a = 5, j++
+ * \endcode
+ *
+ * \see CBotFor
  */
 class CBotListExpression : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotListExpression
-     */
     CBotListExpression();
-
-    /*!
-     * \brief CBotListExpression
-     */
     ~CBotListExpression();
 
     /*!

src/CBot/CBotInstr/CBotListInstr.h

@@ -24,22 +24,13 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotListInstr class Compiles a list of instructions separated by
+ * \brief A list of instructions separated by semicolons - ...; ...; ...; ...;
- * semicolons eg : ... ; ... ; ... ; ... ;
  */
 class CBotListInstr : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotListInstr
-     */
     CBotListInstr();
-
-    /*!
-     * \brief ~CBotListInstr
-     */
     ~CBotListInstr();
 
     /*!

src/CBot/CBotInstr/CBotLogicExpr.h

@@ -24,21 +24,16 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotLogicExpr class
+ * \brief An "inline if" operator - condition ? if_true : if_false
+ * \todo I don't remember the proper name of this thing :/ ~krzys_h
+ *
+ * Compiled in CBotTwoOpExpr
  */
 class CBotLogicExpr : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotLogicExpr
-     */
     CBotLogicExpr();
-
-    /*!
-     * \brief ~CBotLogicExpr
-     */
     ~CBotLogicExpr();
 
     /*!

src/CBot/CBotInstr/CBotNew.cpp

@@ -65,7 +65,7 @@ CBotInstr* CBotNew::Compile(CBotToken* &p, CBotCStack* pStack)
     inst->m_vartoken = *p;
     p = p->GetNext();
 
-    // creates the object on the "job"
+    // creates the object on the stack
     // with a pointer to the object
     CBotVar*    pVar = CBotVar::Create("", pClass);
 

src/CBot/CBotInstr/CBotNew.h

@@ -24,21 +24,13 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotNew class Compile an instruction "new".
+ * \brief Creation of a class instance - "new" operator - new SomeClass()
  */
 class CBotNew : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotNew
-     */
     CBotNew();
-
-    /*!
-     * \brief ~CBotNew
-     */
     ~CBotNew();
 
     /*!

src/CBot/CBotInstr/CBotParExpr.h

@@ -24,27 +24,24 @@
 namespace CBot
 {
 
-////////////////////////////////////////////////////////////////////////////////
+/**
-// possibly an expression in parentheses ( ... )
+ * \brief An expression
-// there is never an instance of this class
+ *
-// being the object returned inside the parenthesis
+ * There is never an instance of this class
-////////////////////////////////////////////////////////////////////////////////
+ *
-// compile either:
+ * Compiles either:
-// instruction in parentheses (...)
+ * * an arithmetic expression in parentheses -- CBotExpression -- (...)
-// a unary expression (negative, not)
+ * * unary operation -- CBotExprUnaire -- -a, +a, ~a, !a, not a
-// variable name
+ * * a variable name -- CBotExprVar
-// variables pre and post-incremented or decremented
+ * * pre- or post- incremented or decremented variable -- CBotPreIncExpr, CBotPostIncExpr -- a++, ++a, a--, --a
-// a given number DefineNum
+ * * a function call -- CBotInstrCall
-// a constant
+ * * a class method call -- CBotInstrMethode
-// procedure call
+ * * number literal (or numerical constant from CBotToken::DefineNum()) -- CBotExprNum
-// new statement
+ * * string literal -- CBotExprAlpha
-//
+ * * boolean literal -- CBotExprBool -- true/false
-// this class has no constructor, because there is never an instance of this class
+ * * null -- CBotExprNull
-// the object returned by Compile is the class corresponding to the instruction
+ * * nan -- CBotExprNan
-////////////////////////////////////////////////////////////////////////////////
+ * * class instance creation with "new" -- CBotNew
-
-/*!
- * \brief The CBotParExpr class
  */
 class CBotParExpr : public CBotInstr
 {
@@ -56,6 +53,10 @@ public:
      * \return
      */
     static CBotInstr* Compile(CBotToken* &p, CBotCStack* pStack);
+
+private:
+    CBotParExpr() = delete;
+    CBotParExpr(const CBotParExpr&) = delete;
 };
 
 } // namespace CBot

src/CBot/CBotInstr/CBotPostIncExpr.h

@@ -24,27 +24,15 @@
 namespace CBot
 {
 
-//////////////////////////////////////////////////////////////////////////////////////
+/**
-// Management of pre-and post increment / decrement
+ * \brief Post increment/decrement
-// There is no routine Compiles, the object is created directly
+ *
-// Compiles in CBotParExpr ::
+ * Compiled in CBotParExpr
-
-/*!
- * \brief The CBotPostIncExpr class
  */
 class CBotPostIncExpr : public CBotInstr
 {
-
 public:
-
-    /*!
-     * \brief CBotPostIncExpr
-     */
     CBotPostIncExpr();
-
-    /*!
-     * \brief ~CBotPostIncExpr
-     */
     ~CBotPostIncExpr();
 
     /*!

src/CBot/CBotInstr/CBotPreIncExpr.h

@@ -24,22 +24,15 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotPreIncExpr class Management of pre increment. There is no
+ * \brief Pre increment/decrement
- * routine Compiles, the object is created directly. Compiles in CBotParExpr
+ *
+ * Compiled in CBotParExpr
  */
 class CBotPreIncExpr : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotPreIncExpr
-     */
     CBotPreIncExpr();
-
-    /*!
-     * \brief ~CBotPreIncExpr
-     */
     ~CBotPreIncExpr();
 
     /*!

src/CBot/CBotInstr/CBotReturn.h

@@ -24,21 +24,13 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotReturn class. Return parameters
+ * \brief The "return" instruction
  */
 class CBotReturn : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotReturn
-     */
     CBotReturn();
-
-    /*!
-     * \brief ~CBotReturn
-     */
     ~CBotReturn();
 
     /*!

src/CBot/CBotInstr/CBotSwitch.h

@@ -24,21 +24,15 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotSwitch class. Compiles instruction "switch"
+ * \brief The switch structure
+ *
+ * \see CBotCase
  */
 class CBotSwitch : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotSwitch
-     */
     CBotSwitch();
-
-    /*!
-     * \brief CBotSwitch
-     */
     ~CBotSwitch();
 
     /*!

src/CBot/CBotInstr/CBotThrow.h

@@ -24,21 +24,13 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotThrow class Compiles instruction "throw".
+ * \brief The "throw" instruction
  */
 class CBotThrow : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotThrow
-     */
     CBotThrow();
-
-    /*!
-     * \brief ~CBotThrow
-     */
     ~CBotThrow();
 
     /*!

src/CBot/CBotInstr/CBotTry.h

@@ -24,21 +24,15 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotTry class Compiles instruction "try"
+ * \brief The "try" structure
+ *
+ * \see CBotCatch
  */
 class CBotTry : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotTry
-     */
     CBotTry();
-
-    /*!
-     * \brief ~CBotTry
-     */
     ~CBotTry();
 
     /*!

src/CBot/CBotInstr/CBotTwoOpExpr.h

@@ -24,28 +24,23 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotTwoOpExpr class All operations with two operands.
+ * \brief Any expression with two operands
- * eg :
+ *
- *      - Opérande1 + Opérande2
+ * Examples:
- *      - Opérande1 > Opérande2
+ * \code
+ * op1 + op2
+ * op1 > op2
+ * \endcode
  */
 class CBotTwoOpExpr : public CBotInstr
 {
 public:
-
-    /*!
-     * \brief CBotTwoOpExpr
-     */
     CBotTwoOpExpr();
-
-    /*!
-     * \brief ~CBotTwoOpExpr
-     */
     ~CBotTwoOpExpr();
 
     /*!
-     * \brief Compile Compiles a instruction of type A op B.
+     * \brief Compiles CBotTwoOpExpr or CBotLogicExpr
      * \param p
      * \param pStack
      * \param pOperations

src/CBot/CBotInstr/CBotWhile.h

@@ -24,8 +24,8 @@
 namespace CBot
 {
 
-/*!
+/**
- * \brief The CBotWhile class Compile an instruction "while".
+ * \brief The "while" loop - while (condition) { ... }
  */
 class CBotWhile : public CBotInstr
 {