From 532e16859dc455f102e9d0c0f94f06eb6a6d8a1b Mon Sep 17 00:00:00 2001 From: David Kolossa Date: Wed, 11 Feb 2009 18:54:10 +0100 Subject: [PATCH] Included first (incomplete) doxygen documentation - Added doxygen config (doxyfile) - Added new build target: make doc - Began documentation for several classes - Minor cleanups during that process --- CMakeLists.txt | 4 + doxyfile | 252 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ src/bbfile.hh | 164 ++++++++++++++++++++++++++++-------- src/entity.hh | 20 +++-- src/item.hh | 35 +++++++- src/kingdom.hh | 70 +++++++++++----- src/object.hh | 44 ++++++++-- src/s2string.cc | 2 +- src/s2string.hh | 42 ++++++---- src/type.hh | 244 +++++++++++++++++++++++++++++++++++++++++------------- 10 files changed, 729 insertions(+), 148 deletions(-) create mode 100644 doxyfile diff --git a/CMakeLists.txt b/CMakeLists.txt index 5abd60e..6ba6b2e 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -4,5 +4,9 @@ project(openstranded) SET(CMAKE_C_FLAGS "-Wall") SET(CMAKE_CXX_FLAGS "-Wall -Wno-non-virtual-dtor") +add_custom_target(doc + doxygen doxyfile +) + add_subdirectory(src) diff --git a/doxyfile b/doxyfile new file mode 100644 index 0000000..364886c --- /dev/null +++ b/doxyfile @@ -0,0 +1,252 @@ +# Doxyfile 1.5.6 + +# This file is used to create the doxygen documentation of the source code. +# Run `make doc' to build it. + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- +DOXYFILE_ENCODING = UTF-8 +PROJECT_NAME = OpenStranded +PROJECT_NUMBER = +OUTPUT_DIRECTORY = doc +CREATE_SUBDIRS = NO +OUTPUT_LANGUAGE = English +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ABBREVIATE_BRIEF = +ALWAYS_DETAILED_SEC = NO +INLINE_INHERITED_MEMB = NO +FULL_PATH_NAMES = YES +STRIP_FROM_PATH = +STRIP_FROM_INC_PATH = +SHORT_NAMES = NO +JAVADOC_AUTOBRIEF = YES +QT_AUTOBRIEF = NO +MULTILINE_CPP_IS_BRIEF = NO +DETAILS_AT_TOP = NO +INHERIT_DOCS = YES +SEPARATE_MEMBER_PAGES = NO +TAB_SIZE = 8 +ALIASES = +OPTIMIZE_OUTPUT_FOR_C = NO +OPTIMIZE_OUTPUT_JAVA = NO +OPTIMIZE_FOR_FORTRAN = NO +OPTIMIZE_OUTPUT_VHDL = NO +BUILTIN_STL_SUPPORT = NO +CPP_CLI_SUPPORT = NO +SIP_SUPPORT = NO +IDL_PROPERTY_SUPPORT = YES +DISTRIBUTE_GROUP_DOC = NO +SUBGROUPING = YES +TYPEDEF_HIDES_STRUCT = NO +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- +EXTRACT_ALL = NO +EXTRACT_PRIVATE = NO +EXTRACT_STATIC = NO +EXTRACT_LOCAL_CLASSES = YES +EXTRACT_LOCAL_METHODS = NO +EXTRACT_ANON_NSPACES = NO +HIDE_UNDOC_MEMBERS = NO +HIDE_UNDOC_CLASSES = NO +HIDE_FRIEND_COMPOUNDS = NO +HIDE_IN_BODY_DOCS = NO +INTERNAL_DOCS = NO +CASE_SENSE_NAMES = YES +HIDE_SCOPE_NAMES = NO +SHOW_INCLUDE_FILES = YES +INLINE_INFO = YES +SORT_MEMBER_DOCS = YES +SORT_BRIEF_DOCS = NO +SORT_GROUP_NAMES = NO +SORT_BY_SCOPE_NAME = NO +GENERATE_TODOLIST = YES +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = YES +GENERATE_DEPRECATEDLIST= YES +ENABLED_SECTIONS = +MAX_INITIALIZER_LINES = 30 +SHOW_USED_FILES = YES +SHOW_DIRECTORIES = NO +SHOW_FILES = YES +SHOW_NAMESPACES = YES +FILE_VERSION_FILTER = +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- +QUIET = NO +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_NO_PARAMDOC = NO +WARN_FORMAT = "$file:$line: $text" +WARN_LOGFILE = +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- +INPUT = "src" +INPUT_ENCODING = UTF-8 +FILE_PATTERNS = *.cc \ + *.hh \ + *.c \ + *.h +RECURSIVE = NO +EXCLUDE = +EXCLUDE_SYMLINKS = NO +EXCLUDE_PATTERNS = +EXCLUDE_SYMBOLS = +EXAMPLE_PATH = +EXAMPLE_PATTERNS = +EXAMPLE_RECURSIVE = NO +IMAGE_PATH = +INPUT_FILTER = +FILTER_PATTERNS = +FILTER_SOURCE_FILES = NO +#--------------------------------------------------------------------------- +# configuration options related to source browsing +#--------------------------------------------------------------------------- +SOURCE_BROWSER = NO +INLINE_SOURCES = NO +STRIP_CODE_COMMENTS = YES +REFERENCED_BY_RELATION = NO +REFERENCES_RELATION = NO +REFERENCES_LINK_SOURCE = YES +USE_HTAGS = NO +VERBATIM_HEADERS = YES +#--------------------------------------------------------------------------- +# configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- +ALPHABETICAL_INDEX = NO +COLS_IN_ALPHA_INDEX = 5 +IGNORE_PREFIX = +#--------------------------------------------------------------------------- +# configuration options related to the HTML output +#--------------------------------------------------------------------------- +GENERATE_HTML = YES +HTML_OUTPUT = html +HTML_FILE_EXTENSION = .html +HTML_HEADER = +HTML_FOOTER = +HTML_STYLESHEET = +HTML_ALIGN_MEMBERS = YES +GENERATE_HTMLHELP = NO +GENERATE_DOCSET = NO +DOCSET_FEEDNAME = "Doxygen generated docs" +DOCSET_BUNDLE_ID = org.doxygen.Project +HTML_DYNAMIC_SECTIONS = NO +CHM_FILE = +HHC_LOCATION = +GENERATE_CHI = NO +CHM_INDEX_ENCODING = +BINARY_TOC = NO +TOC_EXPAND = NO +DISABLE_INDEX = NO +ENUM_VALUES_PER_LINE = 4 +GENERATE_TREEVIEW = NONE +TREEVIEW_WIDTH = 250 +FORMULA_FONTSIZE = 10 +#--------------------------------------------------------------------------- +# configuration options related to the LaTeX output +#--------------------------------------------------------------------------- +GENERATE_LATEX = YES +LATEX_OUTPUT = latex +LATEX_CMD_NAME = latex +MAKEINDEX_CMD_NAME = makeindex +COMPACT_LATEX = NO +PAPER_TYPE = a4wide +EXTRA_PACKAGES = +LATEX_HEADER = +PDF_HYPERLINKS = YES +USE_PDFLATEX = YES +LATEX_BATCHMODE = NO +LATEX_HIDE_INDICES = NO +#--------------------------------------------------------------------------- +# configuration options related to the RTF output +#--------------------------------------------------------------------------- +GENERATE_RTF = NO +RTF_OUTPUT = rtf +COMPACT_RTF = NO +RTF_HYPERLINKS = NO +RTF_STYLESHEET_FILE = +RTF_EXTENSIONS_FILE = +#--------------------------------------------------------------------------- +# configuration options related to the man page output +#--------------------------------------------------------------------------- +GENERATE_MAN = NO +MAN_OUTPUT = man +MAN_EXTENSION = .3 +MAN_LINKS = NO +#--------------------------------------------------------------------------- +# configuration options related to the XML output +#--------------------------------------------------------------------------- +GENERATE_XML = NO +XML_OUTPUT = xml +XML_SCHEMA = +XML_DTD = +XML_PROGRAMLISTING = YES +#--------------------------------------------------------------------------- +# configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- +GENERATE_AUTOGEN_DEF = NO +#--------------------------------------------------------------------------- +# configuration options related to the Perl module output +#--------------------------------------------------------------------------- +GENERATE_PERLMOD = NO +PERLMOD_LATEX = NO +PERLMOD_PRETTY = YES +PERLMOD_MAKEVAR_PREFIX = +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = NO +EXPAND_ONLY_PREDEF = NO +SEARCH_INCLUDES = YES +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = +PREDEFINED = +EXPAND_AS_DEFINED = +SKIP_FUNCTION_MACROS = YES +#--------------------------------------------------------------------------- +# Configuration::additions related to external references +#--------------------------------------------------------------------------- +TAGFILES = +GENERATE_TAGFILE = +ALLEXTERNALS = NO +EXTERNAL_GROUPS = YES +PERL_PATH = /usr/bin/perl +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- +CLASS_DIAGRAMS = YES +MSCGEN_PATH = +HIDE_UNDOC_RELATIONS = YES +HAVE_DOT = NO +DOT_FONTNAME = FreeSans +DOT_FONTPATH = +CLASS_GRAPH = YES +COLLABORATION_GRAPH = YES +GROUP_GRAPHS = YES +UML_LOOK = NO +TEMPLATE_RELATIONS = NO +INCLUDE_GRAPH = YES +INCLUDED_BY_GRAPH = YES +CALL_GRAPH = NO +CALLER_GRAPH = NO +GRAPHICAL_HIERARCHY = YES +DIRECTORY_GRAPH = YES +DOT_IMAGE_FORMAT = png +DOT_PATH = +DOTFILE_DIRS = +DOT_GRAPH_MAX_NODES = 50 +MAX_DOT_GRAPH_DEPTH = 0 +DOT_TRANSPARENT = YES +DOT_MULTI_TARGETS = NO +GENERATE_LEGEND = YES +DOT_CLEANUP = YES +#--------------------------------------------------------------------------- +# Configuration::additions related to the search engine +#--------------------------------------------------------------------------- +SEARCHENGINE = NO diff --git a/src/bbfile.hh b/src/bbfile.hh index ca49e1f..8a422ff 100644 --- a/src/bbfile.hh +++ b/src/bbfile.hh @@ -25,145 +25,241 @@ #include #include +/** + * This is a wrapper class for Blitz3d files. + * It is used to provide compatibility with files created by + * Blitz Basic 3d (e.g. save files) + */ class BBFile { private: std::fstream file; public: - /* + /** * The constructor. - * Opens the Blitz Basic file specified in filePath + * Opens a Blitz Basic compatible file. + * @param filePath Path to the file to be opened */ BBFile (const char *filePath); - /* + /** * The destructor. * Closes the opened file. */ ~BBFile (); - /* - * Overload the extraction operator to allow reading of the supported - * types. - * Note that you can't read lines using the >> operator, use readLine() instead. + + + // + // Overloading the extraction operator + // + + /** + * Read a string from the file. + * Note: You can't read lines using this operator, use readLine() instead. + * @param strBuf The buffer into which the string is written + * @return A reference to the BBFile object + * @see readLine() + * @see readString() */ BBFile& operator>> (std::string &strBuf); + /** + * Read a uint8_t (In B3d: Byte) from the file. + * @param byteBuf The buffer into which the uint8_t is written + * @return A reference to the BBFile object + * @see readByte() + */ BBFile& operator>> (uint8_t &byteBuf); + /** + * Read a uint16_t (In B3d: Short) from the file. + * @param shortBuf The buffer into which the uint16_t is written + * @return A reference to the BBFile object + * @see readShort() + */ BBFile& operator>> (uint16_t &shortBuf); + /** + * Read an int32_t (In B3d: Int) from the file. + * @param intBuf The buffer into which the int32_t is written + * @return A reference to the BBFile object + * @see readInt() + */ BBFile& operator>> (int32_t &intBuf); + /** + * Read a float (In B3d: Float) from the file. + * @param floatBuf Th buffer into which the float is written + * @return A reference to the BBFile object + * @see readFloat() + */ BBFile& operator>> (float &floatBuf); - /* - * Now the same with the insertion operator. - * Again, for writing lines you need to use the writeLine() function + + + // + // Overloading the insertion operator + // + + /** + * Write a string to the file. + * Note: You can't write lines with that operator, use writeLine() instead. + * @param strBuf The buffer from which the string is read + * @return A reference to the BBFile object + * @see writeString() + * @see writeLine() */ BBFile& operator<< (std::string &strBuf); + /** + * Write a uint8_t (In B3d: Byte) to the file. + * @param byteBuf The buffer from which the uint8_t is read + * @return A reference to the BBFile object + * @see writeByte() + */ BBFile& operator<< (uint8_t &byteBuf); + /** + * Write a uint16_t (In B3d: Short) to the file. + * @param shortBuf The buffer from which the uint16_t is read + * @return A reference to the BBFile object + * @see writeShort() + */ BBFile& operator<< (uint16_t &shortBuf); + /** + * Write a int32_t (In B3d: Integer) to the file. + * @param intBuf The buffer from which the int32_t is read + * @return A reference to the BBFile object + * @see writeInt() + */ BBFile& operator<< (int32_t &intBuf); + /** + * Write a float (In B3d: Float) to the file. + * @param floatBuf The buffer from which the float is read + * @return A reference to the BBFile object + * @see writeFloat() + */ BBFile& operator<< (float &floatBuf); - /* - * Reads a string terminated by the ASCII symbols CR (0x0d) and LF (0x0a). - * Returns the read data as a string object. + + + // + // Actual file reading methods + // + + /** + * Reads a line. + * A line is terminated by the ASCII symbols CR (0x0d) and LF (0x0a). + * The read data is removed from the stream. + * @return The read string */ std::string readLine (); - /* - * Reads a string, preceded by its length as an int32_t from the - * stream and removes it afterwards. - * Returns the read data as a string object. + /** + * Reads a string. + * A string is preceded by its length as an int32_t. This method reads the + * string and removes it (including length indicator) from the stream. + * @return The read string */ std::string readString (); - /* + /** * Reads a uint8_t (B3d: Byte) value from the stream and removes it afterwards. - * Returns the read uint8_t value. + * @return The read uint8_t value. */ uint8_t readByte (); - /* + /** * Reads a uint16_t (B3d: Short) value from the stream and removes it afterwards. - * Returns the read short value. + * @return The read short value. */ uint16_t readShort (); - /* + /** * Reads an int32_t (B3d: Int) value from the stream and removes it afterwards. - * Returns the read int32_t value. + * @return The read int32_t value. */ int32_t readInt (); - /* - * Reads a float value from the stream and removes it afterwars. - * Returns the read float value. + /** + * Reads a float value from the stream and removes it afterwards. + * @return The read float value. */ float readFloat (); - /* + + + // + // Actual file writing methods + // + + /** * Writes a string terminated by the ASCII symbols CR (0x0d) and LF (0x0a) * to the stream. + * @param lineWritten The line to be written */ void writeLine (std::string &lineWritten); - /* + /** * Writes a string to the stream. + * @param strWritten The string to be written */ void writeString (std::string &strWritten); - /* + /** * Writes a uint8_t (B3d: Byte) to the stream. + * @param byteWritten The uint8_t to be written */ void writeByte (uint8_t &byteWritten); - /* + /** * Writes a uint16_t (B3d: Short) to the stream. + * @param shortWritten The uint16_t to be written */ void writeShort (uint16_t &shortWritten); - /* + /** * Writes a int32_t (B3d: Int) to the stream. + * @param intWritten The int32_t to be written */ void writeInt (int32_t &intWritten); - /* + /** * Writes a float to the stream. + * @param floatWritten The float to be written */ void writeFloat (float &floatWritten); - /* - * Checks whether a string is a valid B3d line (return true) or not (return false) + /** + * Checks whether a string is a valid B3d line + * @param line The string to be checked + * @return true if line is a valid b3d line, false if not */ bool validLine (std::string &line); diff --git a/src/entity.hh b/src/entity.hh index 88800ee..130e42e 100644 --- a/src/entity.hh +++ b/src/entity.hh @@ -28,7 +28,7 @@ typedef unsigned int ID; -/* +/** * An entity is a single, independent piece on the map. * It belongs to a "kingdom" which defines its most basic properties * (e.g. collectable, controllable...) and a "type" which is @@ -39,18 +39,28 @@ typedef unsigned int ID; class Entity { private: + /** + * The ID of the type as assigned in the constructor. + */ ID typeID; - /* - * Graphical Object + + + /** + * A graphical object */ eal::SceneNode scenenode; public: - /* - * The actual constructor, with the entity's type as argument + /** + * The entity's constructor. + * @param type The ID of the type this entity belongs to */ Entity (ID type); + + /** + * The destructor. + */ virtual ~Entity () {}; }; diff --git a/src/item.hh b/src/item.hh index af3cc69..46b2831 100644 --- a/src/item.hh +++ b/src/item.hh @@ -29,7 +29,7 @@ #define S2_ITEM 3 -/* +/** * This is the class of all entities which belong to the kingdom * "item". * An item is the only entity which can be collected by the player @@ -39,33 +39,60 @@ class ItemEntity: public Entity { public: + /** + * The constructor. + * @param type The ID of the Type the item should belong to + */ ItemEntity (ID type); }; -/* +/** * This is the class of all item types derived from the Item base class. */ class ItemType: public Type { public: + /** + * The constructor. + * @param name The name of the new item type + */ ItemType (const char* name); }; -/* +/** * The Item Kingdom class */ class ItemKingdom: public Kingdom { public: - // Constructor + /** + * The constructor. + */ ItemKingdom (); + + + // // Virtual methods + // + + /** + * Create a new item entity + * @param type The ID of the type the new item should belong to + * @return A pointer to the new Entity + * @see ItemEntity::ItemEntity() + */ Entity* createEntity (ID type); + /** + * Create a new item type + * @param name The name of the new type (visible in editor) + * @return A pointer to the new Type + * @see ItemType::ItemType() + */ Type* createType (const char* name); }; diff --git a/src/kingdom.hh b/src/kingdom.hh index de9ce00..d4666e9 100644 --- a/src/kingdom.hh +++ b/src/kingdom.hh @@ -34,8 +34,8 @@ class Kingdom; typedef unsigned int ID; -/* - * This is a base class for all kingdoms +/** + * This is a base class for all kingdoms. * Originally implemented kingdoms were, roughly summarized, the following: * Units as the only mobile and intelligent (or controllable) entities, * Items as storable tools or resources, @@ -62,63 +62,88 @@ class Kingdom ID highestEntityID; public: - /* - * The constructor, with the kingdom name as argument + /** + * The constructor. + * @param name The name of the kingdom */ Kingdom (const char *name); - /* + /** + * The destructor. * Entities and Types are most likely to be allocated on the heap, * so this destructor is used to free them again */ virtual ~Kingdom (); - /* - * Looks up a certain entity from the kingdom's list by its ID + /** + * Looks up a certain entity from the kingdom's list by its ID. + * @param index The ID of the desired entity + * @return A pointer to the entity, NULL if none is found */ Entity* getEntity (ID index); - /* + /** * Looks up a certain type from the kingdom's list by its ID + * @param index The ID of the desired type + * @return A pointer to the type, NULL if none is found */ Type* getType (ID index); - /* + /** * Checks whether an entity with a certain ID exists + * @param entity ID of the entity + * @return true if the entity exists, false if not */ bool entityExists (ID entity); - /* + /** * Checks whether a type with a certain ID exists + * @param type ID of the type + * @return true if the type exists, false if not */ bool typeExists (ID type); - /* - * Append an entity to the list, automatically assigning an ID - * which is by 1 higher than the currently highest entity ID + /** + * Append an entity to the list. + * This method automatically assigns an ID which is by + * one higher than the currently highest entity ID + * @param type The ID of the type of the entity + * @return A pointer to the appended entity */ Entity* appendEntity (ID type); - /* - * Insert an entity into a specific position of the list, assigning - * the specified ID to it + /** + * Insert an entity into a specific position of the list. + * This method assigns the specified ID to the entity. + * @param type The ID of the type of the entity + * @param entity The desired ID of the entity in the kingdom + * @return A pointer to the inserted entity */ Entity* insertEntity (ID type, ID entity); - /* + /** + * Insert a type. * TypeIDs need to be certain and definite towards the outside, - * so there is only an insertType method defining a certain ID + * so there is only an insertType method defining a certain ID. + * @param name The name of the type + * @param type The desired ID of the type + * @return A pointer to the inserted type */ Type* insertType (const char* name, ID type); + /** + * Insert a type without a name. + * @param type The desired ID of the type + * @return A pointer to the inserted type + */ Type* insertType (ID type); @@ -128,6 +153,7 @@ class Kingdom * Basically, they should just implement the * entity's and type's constructors/destructors for this kingdom */ + virtual Entity* createEntity (ID type); @@ -140,9 +166,11 @@ class Kingdom virtual void destroyType (Type *type); - /* - * Static class members - */ + + + // + // Static class members + // static std::map kingdomList; diff --git a/src/object.hh b/src/object.hh index 38c57cd..fe7005e 100644 --- a/src/object.hh +++ b/src/object.hh @@ -29,21 +29,27 @@ #define S2_OBJECT 1 -/* +/** * This is the class of all entities which belong to the kingdom - * "object". - * An object is an entity which doesn't move, except on script actions. - * In addition, the player's action with objects are mostly limited to - * damaging and destroying them (without scripts). + * "object", derived from the type base class. + * This class represents an object: an entity which doesn't move, + * except on script actions. In addition, the player's action with + * objects are mostly limited to damaging and destroying them + * (without scripts). */ class ObjectEntity: public Entity { public: + /** + * The constructor. + * @param The ID of the ObjectType this entity belongs to + * @see Entity::Entity() + */ ObjectEntity (ID type); }; -/* +/** * This is the class of the object types, derived from the type base * class. * The single ObjectType instances define the default values for new @@ -52,24 +58,46 @@ class ObjectEntity: public Entity class ObjectType: public Type { public: + /** + * The constructor. + * @param name The name of this type (used in editor) + * @see Type::Type() + */ ObjectType (const char* name); }; -/* +/** * Object kingdom class */ class ObjectKingdom: public Kingdom { public: - // Constructor + /** + * The constructor. + */ ObjectKingdom (); + + + // // Virtual methods + // + + /** + * Creates a new ObjectEntity object. + * @param type The ID of the type which the new object should be + * @see ObjectEntity::ObjectEntity() + */ Entity* createEntity (ID type); + /** + * Creates a new ObjectType object. + * @param name The name of this type + * @see ObjectType::ObjectType() + */ Type* createType (const char* name); }; diff --git a/src/s2string.cc b/src/s2string.cc index 4d9ea7d..763be9f 100644 --- a/src/s2string.cc +++ b/src/s2string.cc @@ -1,5 +1,5 @@ /* - * See strandedstring.hh for more information about this file. + * See s2string.hh for more information about this file. * * Copyright (C) 2008 David Kolossa * diff --git a/src/s2string.hh b/src/s2string.hh index 26916e6..b619df7 100644 --- a/src/s2string.hh +++ b/src/s2string.hh @@ -37,34 +37,44 @@ #define inFlag(flag, value) (((flag) & (value)) == (value)) +/** + * This namespace holds functions for easy manipulation of + * strings. + */ namespace s2str { - /* - * This function divides a string into substrings by a token. - * Returns 0 on success and larger 0 when anything went bad. - * Inspired by the PHP function with the same name. - */ + /** + * This function divides a string into substrings by a token. + * Inspired by the PHP function with the same name. + * @param str The string which sohuld be divided + * @param buf The buffer in which the substrings should be saved + * @param token The token which should split the string + * @param count The maximum number of strings to be written into buf + * @return 0 on success, larger than 0 on error + */ int explode (std::string &str, std::string *buf, const char *token, size_t count); - /* - * Converts a string into a float. - * This functions does some checks on the string so use string - * streams if you think you already have a valid float string. - * Returns true if str was valid, if not, it sets the float to 0.0 - * and returns false. - */ + /** + * Converts a string into a float. + * This functions does some checks on the string so use string + * streams if you think you already have a valid float string. + * @param str The string to be conversed + * @param buf the float in which the result is stored + * @return true if string is valid, if not, it sets the float to 0.0 and returns false + */ bool stof (std::string &str, float &buf); - /* + /** * Converts a string into an int. * This function checks the number whether it is a valid integer to allow * user-friendly error-reporting for typos. - * If you don't need them use a string stream instead. - * Returns true if str was valid, if not it sets buf to 0 and returns - * false. + * If you don't need those checks use a string stream instead. + * @param str The string to be conversed + * @param buf The integer in which the result is stored + * @return true if str was valid and conversed, if not, buf is set to 0 and false is returned */ bool stoi (std::string &str, int &buf); diff --git a/src/type.hh b/src/type.hh index c11aa92..c3231cd 100644 --- a/src/type.hh +++ b/src/type.hh @@ -24,14 +24,13 @@ #define STRANDED_TYPE_HH #include -//#include "gfx/gfx.hh" typedef unsigned int ID; -/* - * Types are the prototypes of the single entities. There is one - * type class per kingdom. +/** + * Types are the prototypes of the single entities. + * There is one type class per kingdom. * The single type instances include the information about the types * as read from the definition files. */ @@ -41,7 +40,6 @@ class Type std::string name; float scaleX, scaleY, scaleZ; uint8_t colorR, colorG, colorB; - //s2gfx::Model model; std::string model; std::string iconPath; float fadingDistance; @@ -50,108 +48,236 @@ class Type public: - /* - * The actual constructor, with the name of the type as argument + /** + * The constructor. + * @param name The name of this type (used only in editor) */ Type (const char *name); + /** + * The destructor. + */ virtual ~Type () {}; - /* - * Type name + + + // + // Name + // + /** + * Set the type name. + * @param name The new name of the type */ - void - setName (std::string &name) { this->name = name; } + inline void + setName (const std::string &name) { this->name = name; } - std::string& + /** + * Get the type name. + * @return The current name of the type + */ + inline std::string getName () { return this->name; } - /* - * Model/Mesh + + + // + // Model path + // + + /** + * Set the model. + * The model is specified by the path to the model file. + * @param path Path to the new model file */ - void - setModel (std::string &path) { this->model = path; } + inline void + setModel (const std::string &path) { this->model = path; } - std::string& + /** + * Return the path to the current model. + * @return Path of the current model file + */ + inline std::string getModel () { return this->model; } - /* - * Icon path + + + // + // Icon path + // + + /** + * Set the path to the icon used. + * The icon is the little thumbnail in the editor. + * @param path Path to the new icon file */ - void - setIconPath (std::string &path) { this->iconPath = path; } + inline void + setIconPath (const std::string &path) { this->iconPath = path; } - std::string& + /** + * Return the current icon path. + * @return The path to the current icon file + */ + inline std::string getIconPath () { return this->iconPath; } - /* - * Scale Values + + + // + // Scaling values + // + + /** + * Set the X scaling value. + * The scaling values are divided into their coordinate + * components. + * @param scaleX The new X scaling value */ - void - setScaleX (float scaleX) { this->scaleX = scaleX; } + inline void + setScaleX (const float scaleX) { this->scaleX = scaleX; } - float + /** + * Get the X scaling value. + * @return The current X scaling value + */ + inline float getScaleX () { return this->scaleX; } - void - setScaleY (float scaleY) { this->scaleY = scaleY; } + /** + * Set the Y scaling value. + * @param scaleY The new Y scaling value + */ + inline void + setScaleY (const float scaleY) { this->scaleY = scaleY; } - float + /** + * Get the Y scaling value. + * @return The current Y scaling value + */ + inline float getScaleY () { return this->scaleY; } - void - setScaleZ (float scaleZ) { this->scaleZ = scaleZ; } + /** + * Set the Z scaling value. + * @param scaleZ The new Z scaling value + */ + inline void + setScaleZ (const float scaleZ) { this->scaleZ = scaleZ; } - float + /** + * Get the Z scaling value. + * @return The current Z scaling value + */ + inline float getScaleZ () { return this->scaleZ; } - /* - * Color values + + + // + // Color values + // + + /** + * Set the red value. + * @param colorR The new red value ranging from 0 to 255 */ - void - setColorR (uint8_t colorR) { this->colorR = colorR; } + inline void + setColorR (const uint8_t colorR) { this->colorR = colorR; } - uint8_t + /** + * Get the red value. + * @return The current red value ranging from 0 to 255 + */ + inline uint8_t getColorR () { return this->colorR; } - void - setColorG (uint8_t colorG) { this->colorG = colorG; } + /** + * Set the green value. + * @param colorG The new green value ranging from 0 to 255 + */ + inline void + setColorG (const uint8_t colorG) { this->colorG = colorG; } - uint8_t + /** + * Get the green value + * @return The current green value ranging from 0 to 255 + */ + inline uint8_t getColorG () { return this->colorG; } - void - setColorB (uint8_t colorB) { this->colorB = colorB; } + /** + * Set the blue value + * @param colorB The new blue value ranging from 0 to 255 + */ + inline void + setColorB (const uint8_t colorB) { this->colorB = colorB; } - uint8_t + /** + * Get the blue value + * @return The current blue value ranging from 0 to 255 + */ + inline uint8_t getColorB () { return this->colorB; } - /* - * Autofade value (distance to player when object fades out) + + + // + // Autofading + // + + /** + * Set the Autofading distance. + * This is the distance to the player when an object fades out of sight + * @param fadingDistance The new Autofading distance */ - void - setFadingDistance (float fadingDistance) { this->fadingDistance = fadingDistance; } + inline void + setFadingDistance (const float fadingDistance) { this->fadingDistance = fadingDistance; } - float + /** + * Get the Autofading distance + * @return The current Autofading distance + */ + inline float getFadingDistance () { return this->fadingDistance; } - /* - * Alpha (transparency) value + + + // + // Alpha + // + + /** + * Set the value of transparency (aka alpha channel). + * @param alpha The new alpha value ranging from 0.0 (invisible) to 1.0 (opaque) */ - void - setAlpha (float alpha) { this->alpha = alpha; } + inline void + setAlpha (const float alpha) { this->alpha = alpha; } - float + /** + * Returns the transparency value. + * @return The current alpha value + */ + inline float getAlpha () { return this->alpha; } - /* - * Shine effect + + + // + // Shine effect + // + + /** + * Set the shine value of the model + * @param shine The new shine value */ - void - setShine (float shine) { this->shine = shine; } + inline void + setShine (const float shine) { this->shine = shine; } - float + /** + * Get the shine value of the model + * @return The current shine value + */ + inline float getShine () { return this->shine; } }; -- 2.11.4.GIT