Contents:
All H - files have to have a ".h" - suffix./*************************************************************************** FILE.CPP/FILE.H - description ------------------- begin : DATE copyright : (C) YEAR by AUTHOR email : tuvisionlib@tuvision.de origin : IN WHICH PROJECT THIS FILE HAS BEEN CREATED ***************************************************************************/ /*************************************************************************** * * * This file is part of the TUVision Library. It is free software; you * * can redistribute it and/or modify it under the terms of the * * GNU Library General Public License as published by the Free Software * * Foundation; either version 2 of the License, or (at your option) * * any later version. * * * ***************************************************************************/
Comments are in "Qt" style.
The header files contain only short descriptions. The class is structured as follows:
The implementation files contain the full descriptions of the menmber functions. The member variables are briefly commented in the header file (see below).
Each class description (e.g. the one shown below) in the .h - file
has to have a \class - line in which the tuv - subdirectory is mentioned.
Example: File tuv/CImageByteGray.h has to have the following documentation for
the class CImageByteGray:
/*! ... * ... * \class CImageByteGray CImageByteGray.h tuv/CImageByteGray.h
Comments are required for every member variables and function before initial cvs checkin.
/**********************************************************/ //! One line brief description. /*! * More descriptive text. * * \author name * \author name * * (optional:) * \code * short example code; * \endcode * * \example example-code-filename * * \warning warning-description, exceptional behaviour * \warning warning-description, exceptional behaviour * * \bug known-bug * \bug known-bug * \class CLASSNAME HEADERFILE.H TUV_INCLUDEDIRECTORY/HEADERFILE.H */ /**********************************************************/ class CClass : public CBaseClass { public: // CREATORS CClass(); virtual ~CClass(); // MANIPULATORS /******************************************************/ //! One line brief description. /******************************************************/ void setSomething ( setType type_name); // ACCESSORS /******************************************************/ //! One line brief description. /******************************************************/ return_type getSomething(); protected: // MANIPULATORS ... // ACCESSORS ... private: // MANIPULATORS ... // ACCESSORS ... public: ... static const int CONSTANT=0; // constants are all UPPERCASE ... float d_float; //member are prefixed with d_ ... protected: double d_double; //!< member variable comment private: const string& d_string; };
/*! \page ClassName Name of Page * - \ref CFilterNoiseReductionsyntactic * * * \section CFilterNoiseRedUMexpic example picture * * \image html CFilterNoiseRedution2.jpg "Vorher -> Nachher" * \image latex CFilterNoiseRedution2.jpg "Vorher -> Nachher" * (delete these lines) * \section CFilterNoiseRedUMbe Brief explanation * ... * * \section CFilterNoiseRedUMde Detailled explanation * ... * * \subsection CFilterNoiseRedUMlpf Low pass filter * ... * \subsection CFilterNoiseRedUMnt Next topic * ... * * \section CFilterNoiseRedUMconcl Conclusion * ... */ THE FOLLOWING IS TO ADD TO THE DETAILED DESCRIPTION: /*! \anchor CFilterNoiseReductionUMsyntactic * \ref CFilterNoiseReductionUMsemantic semantic Declaration * * ... detailed decription */ IMAGE-PATH: tuvisionlib\docs\images (here your pictures should be placed) FORMATION: the structure of the semantic documantation: 1. example picture 2. short explanation 3. detailed explanation (subdivided into topics as section) 4. summary (i.e. as diagram) 5. pros and cons
struct SStruct { };
enum EEnum { };
typedef void (*LProc)();
templateclass CTemplateClass { ... };
/**********************************************************/ /*! * More descriptive text. * * \param param_name param-description * \param param_name param-description * \return return-description * * \author name */ /**********************************************************/ ReturnType CClass::functionName(ParamType param_name, ...) { }
Do not forget to include theReturnType name_of_c_function (ParamType param_name, ...) { }
in the ".cpp" C++ implementation file.extern "C" { ReturnType name_of_c_function ( ... ); }
if
statements:
else
statement belongs into the next line.
if (...) { ... } else { ... } if (...) { ... } else if (...) { ... } else if (...) { ... } else { ... }
switch
statements:
case
statement belongs into the next line.
Each case block is encapsulated by curly brackets (i.e. form
an own statement list). switch (...) { case ...: { ... } break; case ...: { ... } break; // EXCEPTION: this case falls through. case ...: { ... } case ...: { ... } break; default: { ... } break; }