From 6fee1ee12b21a24419fd66614ee5f15afa84299f Mon Sep 17 00:00:00 2001 From: krzys-h Date: Mon, 21 Dec 2015 17:54:55 +0100 Subject: [PATCH] Docs for CBotTypResult.h and CBotEnums.h --- src/CBot/CBotEnums.h | 80 ++++++++++++----------- src/CBot/CBotTypResult.h | 137 +++++++++++++++++++++++++-------------- src/ui/controls/edit.h | 2 +- 3 files changed, 132 insertions(+), 87 deletions(-) diff --git a/src/CBot/CBotEnums.h b/src/CBot/CBotEnums.h index 66965169..ee218f7f 100644 --- a/src/CBot/CBotEnums.h +++ b/src/CBot/CBotEnums.h @@ -19,39 +19,43 @@ #pragma once -// Modules inlcude +/** + * \file CBotEnums.h + * \brief Some enum values used across the CBot engine + */ -// Local include - -// Global include - -/*! \brief CBotType Defines known types. This types are modeled on Java types. - * Do not change the order of elements +/** + * \enum CBotType + * \brief Defines known types. This types are modeled on Java types. + * + * Do not change the order of elements. */ enum CBotType { - CBotTypVoid = 0, - CBotTypByte = 1, //n - CBotTypShort = 2, //n - CBotTypChar = 3, //n - CBotTypInt = 4, - CBotTypLong = 5, //n - CBotTypFloat = 6, - CBotTypDouble = 7, //n - CBotTypBoolean = 8, - CBotTypString = 9, + CBotTypVoid = 0, //!< void + CBotTypByte = 1, //!< byte (NOT IMPLEMENTED) + CBotTypShort = 2, //!< short (NOT IMPLEMENTED) + CBotTypChar = 3, //!< char (NOT IMPLEMENTED) + CBotTypInt = 4, //!< int + CBotTypLong = 5, //!< long (NOT IMPLEMENTED) + CBotTypFloat = 6, //!< float + CBotTypDouble = 7, //!< double (NOT IMPLEMENTED) + CBotTypBoolean = 8, //!< bool + CBotTypString = 9, //!< string - CBotTypArrayPointer = 10, // array of variables - CBotTypArrayBody = 11, // same but creates an instance + CBotTypArrayPointer = 10, //!< Pointer to an array (::CBotTypArrayBody) + CBotTypArrayBody = 11, //!< Array - CBotTypPointer = 12, // pointer to an instance - CBotTypNullPointer = 13, // null pointer is special - CBotTypClass = 15, - CBotTypIntrinsic = 16 // instance of a class intrinsic + CBotTypPointer = 12, //!< Pointer to a class (::CBotTypClass or ::CBotTypIntrinsic) + CBotTypNullPointer = 13, //!< Null pointer + CBotTypClass = 15, //!< Class instance + CBotTypIntrinsic = 16 //!< Intrinsic class instance }; -//n = not implemented yet -//! \brief CBotGet Different modes for GetPosition. +/** + * \enum CBotGet + * \brief Different modes for CBotProgram::GetPosition + */ enum CBotGet { GetPosExtern = 1, @@ -60,7 +64,10 @@ enum CBotGet GetPosBloc = 4 }; - +/** + * \enum EID + * \brief This enum contains possible token types + */ enum EID { ID_IF = 2000, @@ -154,12 +161,14 @@ enum EID TX_NAN }; -//////////////////////////////////////////////////////////////////////// -// Error Handling of compilation and execution -//////////////////////////////////////////////////////////////////////// - -// NOTE: These CANNOT overlap with CBotType - +/** + * \enum CBotError + * \brief This enum contains possible CBot error values. Values in range 5000-5999 are compile errors, 6000-6999 are runtime errors + * + * Note that other values ​​may be returned, for example exceptions for user-defined builtin functions, or "throw" instruction + * + * Also note that these can't overlap with CBotType, see CBotTypResult for explanation + */ enum CBotError { CBotNoErr = 0, @@ -227,10 +236,5 @@ enum CBotError CBotErrRead = 6014, //!< error while reading CBotErrWrite = 6015, //!< writing error - // Max errors - TX_MAX, - - // other values ​​may be returned - // for example exceptions returned by external routines - // and " throw " with any number. + TX_MAX, //!< Max errors }; diff --git a/src/CBot/CBotTypResult.h b/src/CBot/CBotTypResult.h index f992f01e..3cfa6fc0 100644 --- a/src/CBot/CBotTypResult.h +++ b/src/CBot/CBotTypResult.h @@ -19,95 +19,136 @@ #pragma once -// Modules inlcude - -// Local include - -// Global include #include class CBotClass; -/* -// to define a result as output, using for example - - // to return a simple Float - return CBotTypResult( CBotTypFloat ); - - - // to return a string array - return CBotTypResult( CBotTypArray, CBotTypResult( CBotTypString ) ); - - // to return un array of array of "point" class - CBotTypResult typPoint( CBotTypIntrinsic, "point" ); - CBotTypResult arrPoint( CBotTypArray, typPoint ); - return CBotTypResult( CBotTypArray, arrPoint ); -*/ - -/** \brief CBotTypResult class to define the complete type of a result*/ +/** + * \class CBotTypResult + * \brief Class to define the complete type of a variable + * + * Examples: + * \code + * // Return a simple "float" variable + * return CBotTypResult( CBotTypFloat ); + * + * // Return an array of "string" variables + * return CBotTypResult( CBotTypArrayPointer, CBotTypResult( CBotTypString ) ); + * + * // Return an array of "point" class + * return CBotTypResult( CBotTypArrayPointer, CBotTypResult( CBotTypArrayPointer, CBotTypResult( CBotTypIntrinsic, "point" ) ) ); + * \endcode + */ class CBotTypResult { public: /** - * \brief CBotTypResult constructor for simple types (CBotTypInt to CBotTypString) - * \param type type of created result, see CBotType + * \brief Constructor for simple types (::CBotTypInt to ::CBotTypString) + * \param type type of created result, see ::CBotType. This can also sometimes be a value from ::CBotError. */ CBotTypResult(int type); - // for simple types (CBotTypInt à CBotTypString) - + /** + * \brief Constructor for pointer types and intrinsic classes + * \param type type of created result, see ::CBotType + * \param name name of the class + */ CBotTypResult(int type, const std::string& name); - // for pointer types and intrinsic classes + /** + * \brief Constructor for instance of a class + * \param type type of created result, see ::CBotType + * \param pClass class type + */ CBotTypResult(int type, CBotClass* pClass); - // for the instance of a class + /** + * \brief Constructor for arrays + * \param type type of created result, see ::CBotType + * \param elem type of array elements + */ CBotTypResult(int type, CBotTypResult elem); - // for arrays of variables + /** + * \brief Copy constructor + */ CBotTypResult(const CBotTypResult& typ); - // for assignments + /** + * \brief Default constructor + */ CBotTypResult(); - // for default + /** + * \brief Destructor + */ ~CBotTypResult(); + /** + * \brief Returns ::CBotType or ::CBotError stored in this object + * \param mode TODO: document this + */ int GetType(int mode = 0) const; - // returns type CBotType* as a result + /** + * \brief Changes ::CBotType or ::CBotError stored in this object + * \param n new value + */ void SetType(int n); - // modifies a type + /** + * \brief Returns CBotClass pointer (for ::CBotTypClass, ::CBotTypPointer) + */ CBotClass* GetClass() const; - // makes the pointer to the class (for CBotTypClass, CBotTypPointer) + /** + * \brief Get size limit of an array (for ::CBotTypArrayBody or ::CBotTypArrayPointer) + */ int GetLimite() const; - // returns limit size of table (CBotTypArray) + /** + * \brief Set size limit of an array (for ::CBotTypArrayBody or ::CBotTypArrayPointer) + * \param n new value + */ void SetLimite(int n); - // set limit to the table - void SetArray(int* max ); - // set limits for a list of dimensions (arrays of arrays) + /** + * \brief Set size limit of an multidimensional array + * \param max TODO: document this + */ + void SetArray(int* max); + /** + * \brief Get type of array elements (for ::CBotTypArrayBody or ::CBotTypArrayPointer) + * \param n new value + */ CBotTypResult& GetTypElem() const; - // returns type of array elements (CBotTypArray) - // rend le type des éléments du tableau (CBotTypArray) + + /** + * \brief Compares whether the types are compatible + * + * This compares the whole object with another + */ bool Compare(const CBotTypResult& typ) const; - // compares whether the types are compatible - bool Eq(int type) const; - // compare type + /** + * \brief Compare type only + * + * This compares the general "type" part of this object, without checking the additional parameters + */ + bool Eq(int type) const; + + /** + * Copy + */ CBotTypResult& operator=(const CBotTypResult& src); - // copy a complete type in another private: - int m_type; - CBotTypResult* m_pNext; // for the types of type - CBotClass* m_pClass; // for the derivatives of class - int m_limite; // limits of tables + int m_type; //!< type, see ::CBotType and ::CBotError + CBotTypResult* m_pNext; //!< type of array element + CBotClass* m_pClass; //!< class type + int m_limite; //!< array limit friend class CBotVarClass; friend class CBotVarPointer; }; diff --git a/src/ui/controls/edit.h b/src/ui/controls/edit.h index 0a453a6c..87112951 100644 --- a/src/ui/controls/edit.h +++ b/src/ui/controls/edit.h @@ -19,7 +19,7 @@ /** - * \file ui/edit.h + * \file ui/controls/edit.h * \brief CEdit class */