From 10b201b9e6d0ec427bd9397a94bce864980d371e Mon Sep 17 00:00:00 2001 From: krzys-h Date: Wed, 30 Dec 2015 19:13:32 +0100 Subject: [PATCH] Description of CBot instructions --- src/CBot/CBotDebug.h | 7 +++ src/CBot/CBotInstr/CBotBlock.h | 24 ++++---- src/CBot/CBotInstr/CBotBoolExpr.h | 15 +++-- src/CBot/CBotInstr/CBotBoolean.h | 12 +--- src/CBot/CBotInstr/CBotBreak.h | 12 +--- src/CBot/CBotInstr/CBotCase.h | 15 ++--- src/CBot/CBotInstr/CBotCatch.h | 12 +--- src/CBot/CBotInstr/CBotClassInst.h | 22 +++---- src/CBot/CBotInstr/CBotCondition.h | 15 +++-- src/CBot/CBotInstr/CBotDo.h | 11 +--- src/CBot/CBotInstr/CBotEmpty.h | 5 +- src/CBot/CBotInstr/CBotExprAlpha.h | 12 +--- src/CBot/CBotInstr/CBotExprBool.h | 12 +--- src/CBot/CBotInstr/CBotExprNan.h | 12 +--- src/CBot/CBotInstr/CBotExprNull.h | 12 +--- src/CBot/CBotInstr/CBotExprNum.h | 14 ++--- src/CBot/CBotInstr/CBotExprUnaire.h | 13 +--- src/CBot/CBotInstr/CBotExprVar.h | 16 ++--- src/CBot/CBotInstr/CBotExpression.h | 30 ++++------ src/CBot/CBotInstr/CBotFieldExpr.h | 13 +--- src/CBot/CBotInstr/CBotFloat.h | 4 +- src/CBot/CBotInstr/CBotFor.h | 12 +--- src/CBot/CBotInstr/CBotFunction.h | 23 +++---- src/CBot/CBotInstr/CBotIString.h | 4 +- src/CBot/CBotInstr/CBotIf.h | 12 +--- src/CBot/CBotInstr/CBotIndexExpr.h | 14 +---- src/CBot/CBotInstr/CBotInstArray.h | 22 +++---- src/CBot/CBotInstr/CBotInstr.h | 80 +++++++++++++++++++------ src/CBot/CBotInstr/CBotInstrCall.h | 14 ++--- src/CBot/CBotInstr/CBotInstrMethode.h | 12 +--- src/CBot/CBotInstr/CBotInt.h | 13 +--- src/CBot/CBotInstr/CBotLeftExpr.h | 33 ++++------ src/CBot/CBotInstr/CBotLeftExprVar.h | 2 +- src/CBot/CBotInstr/CBotListArray.h | 14 +---- src/CBot/CBotInstr/CBotListExpression.h | 29 +++++---- src/CBot/CBotInstr/CBotListInstr.h | 13 +--- src/CBot/CBotInstr/CBotLogicExpr.h | 15 ++--- src/CBot/CBotInstr/CBotNew.cpp | 2 +- src/CBot/CBotInstr/CBotNew.h | 12 +--- src/CBot/CBotInstr/CBotParExpr.h | 43 ++++++------- src/CBot/CBotInstr/CBotPostIncExpr.h | 20 ++----- src/CBot/CBotInstr/CBotPreIncExpr.h | 15 ++--- src/CBot/CBotInstr/CBotReturn.h | 12 +--- src/CBot/CBotInstr/CBotSwitch.h | 14 ++--- src/CBot/CBotInstr/CBotThrow.h | 12 +--- src/CBot/CBotInstr/CBotTry.h | 14 ++--- src/CBot/CBotInstr/CBotTwoOpExpr.h | 23 +++---- src/CBot/CBotInstr/CBotWhile.h | 4 +- 48 files changed, 297 insertions(+), 474 deletions(-) diff --git a/src/CBot/CBotDebug.h b/src/CBot/CBotDebug.h index 6019c2d1..edbb6bf9 100644 --- a/src/CBot/CBotDebug.h +++ b/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); }; diff --git a/src/CBot/CBotInstr/CBotBlock.h b/src/CBot/CBotInstr/CBotBlock.h index 72dc87bb..82dbc9fc 100644 --- a/src/CBot/CBotInstr/CBotBlock.h +++ b/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 diff --git a/src/CBot/CBotInstr/CBotBoolExpr.h b/src/CBot/CBotInstr/CBotBoolExpr.h index 767b6a5f..82b8ca6f 100644 --- a/src/CBot/CBotInstr/CBotBoolExpr.h +++ b/src/CBot/CBotInstr/CBotBoolExpr.h @@ -24,11 +24,12 @@ namespace CBot { -/*! - * \brief The CBotBoolExpr class Compile a statement such as "(condition)" - * 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 - * type CBotExpression +/** + * \brief An expression that results in a boolean value + * + * There is never an instance of this class - it gets compiled into 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 diff --git a/src/CBot/CBotInstr/CBotBoolean.h b/src/CBot/CBotInstr/CBotBoolean.h index e6ad7891..307e8616 100644 --- a/src/CBot/CBotInstr/CBotBoolean.h +++ b/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(); /*! diff --git a/src/CBot/CBotInstr/CBotBreak.h b/src/CBot/CBotInstr/CBotBreak.h index 2f1a8de8..97331322 100644 --- a/src/CBot/CBotInstr/CBotBreak.h +++ b/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(); /*! diff --git a/src/CBot/CBotInstr/CBotCase.h b/src/CBot/CBotInstr/CBotCase.h index fcc7fa89..d100a709 100644 --- a/src/CBot/CBotInstr/CBotCase.h +++ b/src/CBot/CBotInstr/CBotCase.h @@ -24,23 +24,16 @@ namespace CBot { -/*! - * \brief The CBotCase class Compiles instruction "case" we are bound to the - * statement block "switch". +/** + * \brief Instruction "case", part of "switch" structure + * + * \see CBotSwitch */ class CBotCase : public CBotInstr { public: - - /*! - * \brief CBotCase - */ CBotCase(); - - /*! - * \brief ~CBotCase - */ ~CBotCase(); /*! diff --git a/src/CBot/CBotInstr/CBotCatch.h b/src/CBot/CBotInstr/CBotCatch.h index 24d12ca7..96db38a6 100644 --- a/src/CBot/CBotInstr/CBotCatch.h +++ b/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(); /*! diff --git a/src/CBot/CBotInstr/CBotClassInst.h b/src/CBot/CBotInstr/CBotClassInst.h index 431c421c..62b5331e 100644 --- a/src/CBot/CBotInstr/CBotClassInst.h +++ b/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(); /*! diff --git a/src/CBot/CBotInstr/CBotCondition.h b/src/CBot/CBotInstr/CBotCondition.h index 6b1f28fd..491b7579 100644 --- a/src/CBot/CBotInstr/CBotCondition.h +++ b/src/CBot/CBotInstr/CBotCondition.h @@ -24,10 +24,13 @@ namespace CBot { -/*! - * \brief The CBotCondition class This class has no constructor, because there - * is never an instance of this class the object returned by Compile is usually - * type CBotExpression +/** + * \brief A condition - boolean expression enclosed in brackets - (condition) + * + * 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 diff --git a/src/CBot/CBotInstr/CBotDo.h b/src/CBot/CBotInstr/CBotDo.h index ffe6287e..294ad161 100644 --- a/src/CBot/CBotInstr/CBotDo.h +++ b/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(); /*! diff --git a/src/CBot/CBotInstr/CBotEmpty.h b/src/CBot/CBotInstr/CBotEmpty.h index 0f2c3284..71d91dc3 100644 --- a/src/CBot/CBotInstr/CBotEmpty.h +++ b/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 { diff --git a/src/CBot/CBotInstr/CBotExprAlpha.h b/src/CBot/CBotInstr/CBotExprAlpha.h index c61d44be..17d9163a 100644 --- a/src/CBot/CBotInstr/CBotExprAlpha.h +++ b/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(); /*! diff --git a/src/CBot/CBotInstr/CBotExprBool.h b/src/CBot/CBotInstr/CBotExprBool.h index 19237423..fb8fd935 100644 --- a/src/CBot/CBotInstr/CBotExprBool.h +++ b/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(); /*! diff --git a/src/CBot/CBotInstr/CBotExprNan.h b/src/CBot/CBotInstr/CBotExprNan.h index 17413813..dd5416a2 100644 --- a/src/CBot/CBotInstr/CBotExprNan.h +++ b/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(); /*! diff --git a/src/CBot/CBotInstr/CBotExprNull.h b/src/CBot/CBotInstr/CBotExprNull.h index 527158ad..a18cce47 100644 --- a/src/CBot/CBotInstr/CBotExprNull.h +++ b/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(); /*! diff --git a/src/CBot/CBotInstr/CBotExprNum.h b/src/CBot/CBotInstr/CBotExprNum.h index dc3bc85f..42bd4c8e 100644 --- a/src/CBot/CBotInstr/CBotExprNum.h +++ b/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(); /*! diff --git a/src/CBot/CBotInstr/CBotExprUnaire.h b/src/CBot/CBotInstr/CBotExprUnaire.h index 4a53d43e..83d679c9 100644 --- a/src/CBot/CBotInstr/CBotExprUnaire.h +++ b/src/CBot/CBotInstr/CBotExprUnaire.h @@ -24,22 +24,13 @@ namespace CBot { -/*! - * \brief The CBotExprUnaire class Unary expression. Compile an unary expression - * eg : (+, * -, not, !, ~) +/** + * \brief Unary expression - +a, -a, !a, ~a, not a */ class CBotExprUnaire : public CBotInstr { public: - - /*! - * \brief CBotExprUnaire - */ CBotExprUnaire(); - - /*! - * \brief ~CBotExprUnaire - */ ~CBotExprUnaire(); /*! diff --git a/src/CBot/CBotInstr/CBotExprVar.h b/src/CBot/CBotInstr/CBotExprVar.h index 73062d69..ba3f54b8 100644 --- a/src/CBot/CBotInstr/CBotExprVar.h +++ b/src/CBot/CBotInstr/CBotExprVar.h @@ -27,22 +27,16 @@ namespace CBot { -/*! - * \brief The CBotExprVar class Expression for the variable name. Compile a - * variable name check that it is known on the stack and it has been initialized. +/** + * \brief Expression representing a variable name + * + * 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(); /*! diff --git a/src/CBot/CBotInstr/CBotExpression.h b/src/CBot/CBotInstr/CBotExpression.h index 95ae427b..80cf1b86 100644 --- a/src/CBot/CBotInstr/CBotExpression.h +++ b/src/CBot/CBotInstr/CBotExpression.h @@ -26,32 +26,22 @@ namespace CBot { -/*! - * \brief The CBotExpression class Compiles a statement with or without - * assignment. - * eg : - * - x = a; - * - x * y + 3; - * - x = 123 - * - z * 5 + 4 +/** + * \brief An arithmetic expression, with or without assignment + * + * Examples: + * \code + * x = a + * x * y + 3 + * 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(); /*! diff --git a/src/CBot/CBotInstr/CBotFieldExpr.h b/src/CBot/CBotInstr/CBotFieldExpr.h index 566b2f8a..8feecc63 100644 --- a/src/CBot/CBotInstr/CBotFieldExpr.h +++ b/src/CBot/CBotInstr/CBotFieldExpr.h @@ -24,22 +24,13 @@ namespace CBot { -/*! - * \brief The CBotFieldExpr class Management of the fields of an instance - * (dot operator) eg : toto.x +/** + * \brief Accessing a class field using dot operator - toto.x */ class CBotFieldExpr : public CBotInstr { public: - - /*! - * \brief CBotFieldExpr - */ CBotFieldExpr(); - - /*! - * \brief ~CBotFieldExpr - */ ~CBotFieldExpr(); /*! diff --git a/src/CBot/CBotInstr/CBotFloat.h b/src/CBot/CBotInstr/CBotFloat.h index 2af20165..6feaca36 100644 --- a/src/CBot/CBotInstr/CBotFloat.h +++ b/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 { diff --git a/src/CBot/CBotInstr/CBotFor.h b/src/CBot/CBotInstr/CBotFor.h index 4f72db93..4b9fde8c 100644 --- a/src/CBot/CBotInstr/CBotFor.h +++ b/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(); /*! diff --git a/src/CBot/CBotInstr/CBotFunction.h b/src/CBot/CBotInstr/CBotFunction.h index 3cc051d0..510ba1b1 100644 --- a/src/CBot/CBotInstr/CBotFunction.h +++ b/src/CBot/CBotInstr/CBotFunction.h @@ -26,22 +26,23 @@ namespace CBot { -/*! - * \brief The CBotFunction class A function declaration. Compilation of various - * functions declared by the user +/** + * \brief A function declaration in the code + * + * 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(); /*! diff --git a/src/CBot/CBotInstr/CBotIString.h b/src/CBot/CBotInstr/CBotIString.h index 7f7f4564..9430e44d 100644 --- a/src/CBot/CBotInstr/CBotIString.h +++ b/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 { diff --git a/src/CBot/CBotInstr/CBotIf.h b/src/CBot/CBotInstr/CBotIf.h index f83a55aa..364da0fb 100644 --- a/src/CBot/CBotInstr/CBotIf.h +++ b/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(); /*! diff --git a/src/CBot/CBotInstr/CBotIndexExpr.h b/src/CBot/CBotInstr/CBotIndexExpr.h index ad0bd08c..f161f08b 100644 --- a/src/CBot/CBotInstr/CBotIndexExpr.h +++ b/src/CBot/CBotInstr/CBotIndexExpr.h @@ -24,23 +24,13 @@ namespace CBot { -/*! - * \brief The CBotIndexExpr class Index management for arrays - * eg : - * - array [ expression ] +/** + * \brief Instruction accessing an array element - array[x] */ class CBotIndexExpr : public CBotInstr { public: - - /*! - * \brief CBotIndexExpr - */ CBotIndexExpr(); - - /*! - * \brief ~CBotIndexExpr - */ ~CBotIndexExpr(); /*! diff --git a/src/CBot/CBotInstr/CBotInstArray.h b/src/CBot/CBotInstr/CBotInstArray.h index 1f55c222..3ba0b006 100644 --- a/src/CBot/CBotInstr/CBotInstArray.h +++ b/src/CBot/CBotInstr/CBotInstArray.h @@ -24,24 +24,20 @@ namespace CBot { -/*! - * \brief The CBotInstArray class Definition of an array. - * Defining an array of any type +/** + * \brief Definition of 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 GetDebugLinks(); diff --git a/src/CBot/CBotInstr/CBotInstr.h b/src/CBot/CBotInstr/CBotInstr.h index a92470c8..0f8bf1cf 100644 --- a/src/CBot/CBotInstr/CBotInstr.h +++ b/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= shape=box3d color=cyan] + * instr00000000015304D0 [label=<CBotInstrArray
int[]>] + * instr0000000001530870 [label=<CBotExpression>] + * instr0000000001530920 [label=<CBotLeftExpr
x>] + * instr00000000015309D0 [label=<CBotIndexExpr>] + * instr0000000001530DC0 [label=<CBotExprNum
(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=<CBotInstrArray
int[][]>] + * instr00000000015315F0 [label=<CBotInt>] + * instr0000000001531C20 [label=<CBotLeftExprVar
z>] + * instr00000000015315F0 -> instr0000000001531C20 [label="m_var" weight=5] + * instr0000000001530E80 -> instr00000000015315F0 [label="m_next2b" weight=5] + * { rank=same; instr0000000001530E80; instr00000000015315F0; } + * instr0000000001530B50 [label=<CBotExprVar
x>] + * instr0000000001531700 [label=<CBotIndexExpr>] + * instr0000000001531B60 [label=<CBotExprNum
(int) 1>] + * instr0000000001531700 -> instr0000000001531B60 [label="m_expr" weight=5] + * instr0000000001530B50 -> instr0000000001531700 [label="m_next3" weight=5] + * instr0000000001531A00 [label=<CBotExprNum
(int) 10>] + * instr0000000001530B50 -> instr0000000001531A00 [label="m_next3b" weight=5] + * instr0000000001530E80 -> instr0000000001530B50 [label="m_next3b" weight=5] + * instr0000000001530A80 [label=<CBotLeftExprVar
y>] + * instr0000000001530E80 -> instr0000000001530A80 [label="m_var" weight=5] + * instr0000000001530870 -> instr0000000001530E80 [label="m_next" weight=1] + * { rank=same; instr0000000001530870; instr0000000001530E80; } + * instr0000000001530C80 [label=<CBotExprNum
(int) 4>] + * instr0000000001530870 -> instr0000000001530C80 [label="m_rightop" weight=5] + * instr00000000015304D0 -> instr0000000001530870 [label="m_next" weight=1] + * { rank=same; instr00000000015304D0; instr0000000001530870; } + * instr0000000001530670 [label=<CBotEmpty>] + * instr00000000015304D0 -> instr0000000001530670 [label="m_next3b" weight=5] + * instr00000000015305A0 [label=<CBotLeftExprVar
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 GetDebugLinks(); protected: - //! Keeps the token. CBotToken m_token; //! Linked command. diff --git a/src/CBot/CBotInstr/CBotInstrCall.h b/src/CBot/CBotInstr/CBotInstrCall.h index 9343f78b..610659fb 100644 --- a/src/CBot/CBotInstr/CBotInstrCall.h +++ b/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(); /*! diff --git a/src/CBot/CBotInstr/CBotInstrMethode.h b/src/CBot/CBotInstr/CBotInstrMethode.h index 75b83604..089d4af8 100644 --- a/src/CBot/CBotInstr/CBotInstrMethode.h +++ b/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(); /*! diff --git a/src/CBot/CBotInstr/CBotInt.h b/src/CBot/CBotInstr/CBotInt.h index df4de32b..92bb17e0 100644 --- a/src/CBot/CBotInstr/CBotInt.h +++ b/src/CBot/CBotInstr/CBotInt.h @@ -24,22 +24,13 @@ namespace CBot { -/*! - * \brief The CBotInt class Definition of an integer variable - * int a, b = 12; +/** + * \brief Definition of an integer variable - int a, b = 12 */ class CBotInt : public CBotInstr { public: - - /*! - * \brief CBotInt - */ CBotInt(); - - /*! - * \brief ~CBotInt - */ ~CBotInt(); /*! diff --git a/src/CBot/CBotInstr/CBotLeftExpr.h b/src/CBot/CBotInstr/CBotLeftExpr.h index 989c3c26..35ac536f 100644 --- a/src/CBot/CBotInstr/CBotLeftExpr.h +++ b/src/CBot/CBotInstr/CBotLeftExpr.h @@ -24,36 +24,29 @@ namespace CBot { -/*! - * \brief The CBotLeftExpr class Accept the expressions that be to the left of - * assignment. +/** + * \brief Compilation of left side of an 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 diff --git a/src/CBot/CBotInstr/CBotLeftExprVar.h b/src/CBot/CBotInstr/CBotLeftExprVar.h index 59c21573..52d77b3e 100644 --- a/src/CBot/CBotInstr/CBotLeftExprVar.h +++ b/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 { diff --git a/src/CBot/CBotInstr/CBotListArray.h b/src/CBot/CBotInstr/CBotListArray.h index c0198456..fe1781b4 100644 --- a/src/CBot/CBotInstr/CBotListArray.h +++ b/src/CBot/CBotInstr/CBotListArray.h @@ -24,23 +24,13 @@ namespace CBot { -/*! - * \brief The CBotListArray class Definition of a assignment list for a table - * int [ ] a [ ] = ( ( 1, 2, 3 ) , ( 3, 2, 1 ) ) ; +/** + * \brief Compilation of assignment of an array - {{1, 2, 3}, {3, 2, 1}} */ class CBotListArray : public CBotInstr { - public: - - /*! - * \brief CBotListArray - */ CBotListArray(); - - /*! - * \brief ~CBotListArray - */ ~CBotListArray(); /*! diff --git a/src/CBot/CBotInstr/CBotListExpression.h b/src/CBot/CBotInstr/CBotListExpression.h index 2208f37e..6fac706e 100644 --- a/src/CBot/CBotInstr/CBotListExpression.h +++ b/src/CBot/CBotInstr/CBotListExpression.h @@ -24,22 +24,29 @@ namespace CBot { -/*! - * \brief The CBotListExpression class. Compiles a list of expressions is used - * only in "for" statement in incrementing and intitialisation. +/** + * \brief Compile a comma-separated list of expressions or variable definitions + * + * 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(); /*! diff --git a/src/CBot/CBotInstr/CBotListInstr.h b/src/CBot/CBotInstr/CBotListInstr.h index 9c252716..c95316f7 100644 --- a/src/CBot/CBotInstr/CBotListInstr.h +++ b/src/CBot/CBotInstr/CBotListInstr.h @@ -24,22 +24,13 @@ namespace CBot { -/*! - * \brief The CBotListInstr class Compiles a list of instructions separated by - * semicolons eg : ... ; ... ; ... ; ... ; +/** + * \brief A list of instructions separated by semicolons - ...; ...; ...; ...; */ class CBotListInstr : public CBotInstr { public: - - /*! - * \brief CBotListInstr - */ CBotListInstr(); - - /*! - * \brief ~CBotListInstr - */ ~CBotListInstr(); /*! diff --git a/src/CBot/CBotInstr/CBotLogicExpr.h b/src/CBot/CBotInstr/CBotLogicExpr.h index fde57daf..899b392c 100644 --- a/src/CBot/CBotInstr/CBotLogicExpr.h +++ b/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(); /*! diff --git a/src/CBot/CBotInstr/CBotNew.cpp b/src/CBot/CBotInstr/CBotNew.cpp index 4354f249..4fd94f71 100644 --- a/src/CBot/CBotInstr/CBotNew.cpp +++ b/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); diff --git a/src/CBot/CBotInstr/CBotNew.h b/src/CBot/CBotInstr/CBotNew.h index 9a0e94ec..4645d87b 100644 --- a/src/CBot/CBotInstr/CBotNew.h +++ b/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(); /*! diff --git a/src/CBot/CBotInstr/CBotParExpr.h b/src/CBot/CBotInstr/CBotParExpr.h index fb186b32..636c172b 100644 --- a/src/CBot/CBotInstr/CBotParExpr.h +++ b/src/CBot/CBotInstr/CBotParExpr.h @@ -24,27 +24,24 @@ namespace CBot { -//////////////////////////////////////////////////////////////////////////////// -// possibly an expression in parentheses ( ... ) -// there is never an instance of this class -// being the object returned inside the parenthesis -//////////////////////////////////////////////////////////////////////////////// -// compile either: -// instruction in parentheses (...) -// a unary expression (negative, not) -// variable name -// variables pre and post-incremented or decremented -// a given number DefineNum -// a constant -// procedure call -// new statement -// -// this class has no constructor, because there is never an instance of this class -// the object returned by Compile is the class corresponding to the instruction -//////////////////////////////////////////////////////////////////////////////// - -/*! - * \brief The CBotParExpr class +/** + * \brief An expression + * + * There is never an instance of this class + * + * Compiles either: + * * an arithmetic expression in parentheses -- CBotExpression -- (...) + * * unary operation -- CBotExprUnaire -- -a, +a, ~a, !a, not a + * * a variable name -- CBotExprVar + * * pre- or post- incremented or decremented variable -- CBotPreIncExpr, CBotPostIncExpr -- a++, ++a, a--, --a + * * a function call -- CBotInstrCall + * * a class method call -- CBotInstrMethode + * * number literal (or numerical constant from CBotToken::DefineNum()) -- CBotExprNum + * * string literal -- CBotExprAlpha + * * boolean literal -- CBotExprBool -- true/false + * * null -- CBotExprNull + * * nan -- CBotExprNan + * * class instance creation with "new" -- CBotNew */ 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 diff --git a/src/CBot/CBotInstr/CBotPostIncExpr.h b/src/CBot/CBotInstr/CBotPostIncExpr.h index 0acc0147..e1600b03 100644 --- a/src/CBot/CBotInstr/CBotPostIncExpr.h +++ b/src/CBot/CBotInstr/CBotPostIncExpr.h @@ -24,27 +24,15 @@ namespace CBot { -////////////////////////////////////////////////////////////////////////////////////// -// Management of pre-and post increment / decrement -// There is no routine Compiles, the object is created directly -// Compiles in CBotParExpr :: - -/*! - * \brief The CBotPostIncExpr class +/** + * \brief Post increment/decrement + * + * Compiled in CBotParExpr */ class CBotPostIncExpr : public CBotInstr { - public: - - /*! - * \brief CBotPostIncExpr - */ CBotPostIncExpr(); - - /*! - * \brief ~CBotPostIncExpr - */ ~CBotPostIncExpr(); /*! diff --git a/src/CBot/CBotInstr/CBotPreIncExpr.h b/src/CBot/CBotInstr/CBotPreIncExpr.h index 0aff5f6e..600f91ac 100644 --- a/src/CBot/CBotInstr/CBotPreIncExpr.h +++ b/src/CBot/CBotInstr/CBotPreIncExpr.h @@ -24,22 +24,15 @@ namespace CBot { -/*! - * \brief The CBotPreIncExpr class Management of pre increment. There is no - * routine Compiles, the object is created directly. Compiles in CBotParExpr +/** + * \brief Pre increment/decrement + * + * Compiled in CBotParExpr */ class CBotPreIncExpr : public CBotInstr { public: - - /*! - * \brief CBotPreIncExpr - */ CBotPreIncExpr(); - - /*! - * \brief ~CBotPreIncExpr - */ ~CBotPreIncExpr(); /*! diff --git a/src/CBot/CBotInstr/CBotReturn.h b/src/CBot/CBotInstr/CBotReturn.h index 34304e75..b652bac0 100644 --- a/src/CBot/CBotInstr/CBotReturn.h +++ b/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(); /*! diff --git a/src/CBot/CBotInstr/CBotSwitch.h b/src/CBot/CBotInstr/CBotSwitch.h index 13aa375d..fd148254 100644 --- a/src/CBot/CBotInstr/CBotSwitch.h +++ b/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(); /*! diff --git a/src/CBot/CBotInstr/CBotThrow.h b/src/CBot/CBotInstr/CBotThrow.h index dd6dd2b7..f9c46ab9 100644 --- a/src/CBot/CBotInstr/CBotThrow.h +++ b/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(); /*! diff --git a/src/CBot/CBotInstr/CBotTry.h b/src/CBot/CBotInstr/CBotTry.h index 2bb5c03f..af61948f 100644 --- a/src/CBot/CBotInstr/CBotTry.h +++ b/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(); /*! diff --git a/src/CBot/CBotInstr/CBotTwoOpExpr.h b/src/CBot/CBotInstr/CBotTwoOpExpr.h index 26b47910..ea33ee35 100644 --- a/src/CBot/CBotInstr/CBotTwoOpExpr.h +++ b/src/CBot/CBotInstr/CBotTwoOpExpr.h @@ -24,28 +24,23 @@ namespace CBot { -/*! - * \brief The CBotTwoOpExpr class All operations with two operands. - * eg : - * - Opérande1 + Opérande2 - * - Opérande1 > Opérande2 +/** + * \brief Any expression with two operands + * + * Examples: + * \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 diff --git a/src/CBot/CBotInstr/CBotWhile.h b/src/CBot/CBotInstr/CBotWhile.h index f1e13551..9aed46c9 100644 --- a/src/CBot/CBotInstr/CBotWhile.h +++ b/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 {