adding doxygen styled comments ..

Author: graetz23

source/hashcc/hashcc.h

@@ -1,5 +1,6 @@
 /**
  * @file hashcc.h
+ * @brief Main include file for HASHCC library
  * @author Christian (graetz23@gmail.com)
  *
  * HASHCC is distributed under the MIT License (MIT); this file is part of.
@@ -23,6 +24,21 @@
  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
+ *
+ * @defgroup HASHCC HASHCC Library
+ * @brief Template-based C++ Hash Map Library
+ *
+ * HASHCC is an object-oriented C++ hash map library based on C++ templates.
+ * It implements a trie-like hash tree data structure, providing efficient
+ * key-value storage with customizable hash functions.
+ *
+ * @li @ref Types - Core type definitions
+ * @li @ref STC - Static character tables
+ * @li @ref TYP - Type system and tree structures
+ * @li @ref ERR - Error handling
+ * @li @ref FNC - Hash functions
+ * @li @ref DMY - Dummy/placeholder objects
+ * @li @ref OBJ - Hash map objects
  */
 
 #ifndef __hashcc_h__
@@ -42,16 +58,21 @@
 
 namespace HASHCC {
 
-/// use and share by the MIT License (MIT)
+/** @brief License identifier */
 #define _HASHCC_LICENSE_ "MIT"
 
-/// from http://www.kleimo.com/random/name.cfm female, 1, 99
-// Pauletta Freshley 20090926 0.00
-// Deeaan Lampel 20160106 0.10
-#define _HASHCC_PACKAGE_ "Agnes Newton" // since 20200307
+/**
+ * @brief Package name
+ * @details From http://www.kleimo.com/random/name.cfm female, 1, 99
+ * - Pauletta Freshley 20090926 0.00
+ * - Deeaan Lampel 20160106 0.10
+ */
+#define _HASHCC_PACKAGE_ "Agnes Newton"
 
-/// first load test are done for prototype of binary hash function and tree
+/** @brief Version number */
 #define _HASHCC_VERSION_NO_ "0.20"
+
+/** @brief Version date (YYYYMMDD) */
 #define _HASHCC_VERSION_DATE_ 20200307
 
 } // namespace HASHCC

source/hashcc/hashccDmy.h

@@ -1,5 +1,6 @@
 /**
  * @file hashccDmy.h
+ * @brief Dummy/placeholder namespace and object includes
  * @author Christian (graetz23@gmail.com)
  *
  * HASHCC is distributed under the MIT License (MIT); this file is part of.
@@ -23,6 +24,12 @@
  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
+ *
+ * @defgroup DMY Dummy Objects
+ * @brief Dummy/placeholder namespace for testing and development.
+ *
+ * The DMY namespace provides dummy/placeholder objects used for
+ * testing and development purposes.
  */
 
 #ifndef __hashccDmy_h__

source/hashcc/hashccDmyObject.h

@@ -1,5 +1,6 @@
 /**
  * @file hashccDmyObject.h
+ * @brief Dummy object class for testing
  * @author Christian (graetz23@gmail.com)
  *
  * HASHCC is distributed under the MIT License (MIT); this file is part of.
@@ -23,6 +24,12 @@
  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
+ *
+ * @class HASHCC::DMY::Object
+ * @brief Dummy object class for testing.
+ * @ingroup DMY
+ *
+ * A simple placeholder used object class for testing the hash map.
  */
 
 #ifndef __hashccDmyObject_h__
@@ -46,18 +53,28 @@ namespace DMY {
 
 typedef HASHCC::String String; // namespace typedef
 
-class /// class as pattern for following classes
-Object {
+/**
+ * @class HASHCC::DMY::Object
+ * @brief Dummy object class for testing.
+ * @ingroup DMY
+ */
+class Object {
  public:
 
-  Object( void ); /// constructor
-  Object( String string ); /// constructor
-  virtual ~Object( void ); /// destructor
+  /** @brief Default constructor */
+  Object( void );
+  /** @brief Construct with string */
+  Object( String string );
+  /** @brief Destructor */
+  virtual ~Object( void );
 
-  String getString( void ); /// returns stored string
-  void setString( String string ); /// stores a string
+  /** @brief Returns stored string */
+  String getString( void );
+  /** @brief Stores a string */
+  void setString( String string );
 
-  friend std::ostream& operator << ( std::ostream& s, Object& o ); /// std::cout
+  /** @brief Stream output operator */
+  friend std::ostream& operator << ( std::ostream& s, Object& o );
   friend std::ostream& operator << ( std::ostream& s, Object* o ); /// std::cout
 
  protected:

source/hashcc/hashccErr.h

@@ -1,5 +1,6 @@
 /**
  * @file hashccErr.h
+ * @brief Error handling namespace and includes
  * @author Christian (graetz23@gmail.com)
  *
  * HASHCC is distributed under the MIT License (MIT); this file is part of.
@@ -23,6 +24,16 @@
  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
+ *
+ * @defgroup ERR Error Handling
+ * @brief Exception classes for error handling in HASHCC.
+ *
+ * The ERR namespace provides exception classes for handling recoverable
+ * and non-recoverable errors in the HASHCC library.
+ *
+ * @li @ref ERR::Exception - Base exception class
+ * @li @ref ERR::Failure - Recoverable exceptions
+ * @li @ref ERR::Error - Non-recoverable errors
  */
 #ifndef __hashccErr_h__
 #define __hashccErr_h__

source/hashcc/hashccErrError.h

@@ -1,5 +1,6 @@
 /**
  * @file hashccErrError.h
+ * @brief Non-recoverable error exception class
  * @author Christian (graetz23@gmail.com)
  *
  * HASHCC is distributed under the MIT License (MIT); this file is part of.
@@ -23,6 +24,13 @@
  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
+ *
+ * @class HASHCC::ERR::Error
+ * @brief Non-recoverable error exception.
+ * @ingroup ERR
+ *
+ * This exception class represents non-recoverable errors that should
+ * cause the program to terminate. It inherits from Exception.
  */
 
 #ifndef __hashccErrError_h__
@@ -44,22 +52,39 @@ namespace ERR {
 
 /******************************************************************************/
 
+/**
+ * @class HASHCC::ERR::Error
+ * @brief Non-recoverable error exception.
+ * @ingroup ERR
+ *
+ * This exception class represents non-recoverable errors that should
+ * cause the program to terminate. It inherits from Exception.
+ */
 class /// class for marking a non recoverable error
 Error : public Exception { // for real errors
  public:
 
-  Error( void ); /// constructor
-  Error( std::exception e ); /// constructor
-  Error( cChar* message ); /// constructor overloaded
-  Error( String message ); /// constructor overloaded
-  Error( String message, Int16 lineNo ); /// use __LINE__ @ lineNo
-  Error( String message, Char* fileName ); /// use __FILE__ @ fileName
-  Error( String message, Char* fileName, Int16 lineNo ); /// use __FILE__ @ fileName and __LINE__ @ lineNo
-  virtual ~Error( void ); /// destructor
+  /** @brief Default constructor */
+  Error( void ); 
+  /** @brief Construct from std::exception */
+  Error( std::exception e ); 
+  /** @brief Construct with C-string message */
+  Error( cChar* message ); 
+  /** @brief Construct with String message */
+  Error( String message ); 
+  /** @brief Construct with message and line number */
+  Error( String message, Int16 lineNo ); 
+  /** @brief Construct with message and filename */
+  Error( String message, Char* fileName ); 
+  /** @brief Construct with message, filename and line number */
+  Error( String message, Char* fileName, Int16 lineNo ); 
+  /** @brief Destructor */
+  virtual ~Error( void ); 
 
  protected:
 
-  virtual void mark( void ); /// mark an exception
+  /** @brief Marks the exception */
+  virtual void mark( void ); 
 
 }; // class Error
 

source/hashcc/hashccErrException.h

@@ -1,5 +1,6 @@
 /**
  * @file hashccErrException.h
+ * @brief Base exception class for HASHCC
  * @author Christian (graetz23@gmail.com)
  *
  * HASHCC is distributed under the MIT License (MIT); this file is part of.
@@ -23,6 +24,14 @@
  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
+ *
+ * @class HASHCC::ERR::Exception
+ * @brief Base exception class for all HASHCC exceptions.
+ * @ingroup ERR
+ *
+ * This is the base class for all exceptions in the HASHCC library.
+ * It provides basic exception handling functionality including
+ * message storage, reporting, and error output.
  */
 
 #ifndef __hashccErrException_h__
@@ -44,40 +53,73 @@ namespace ERR {
 
 /******************************************************************************/
 
+/**
+ * @defgroup CharTypes Character Types
+ * @brief Character type definitions for ERR namespace
+ */
+
+/** @brief Character type @ingroup CharTypes */
 typedef HASHCC::Char       Char; // stc namespace typedef
+/** @brief Constant character type @ingroup CharTypes */
 typedef HASHCC::cChar     cChar; // stc namespace typedef
+/** @brief String type @ingroup CharTypes */
 typedef HASHCC::String   String; // stc namespace typedef
 
 /******************************************************************************/
 
+/**
+ * @class HASHCC::ERR::Exception
+ * @brief Base exception class for all HASHCC exceptions.
+ * @ingroup ERR
+ *
+ * This is the base class for all exceptions in the HASHCC library.
+ * It provides basic exception handling functionality including
+ * message storage, reporting, and error output.
+ */
 class /// base class for errors
 Exception {
  public:
 
-  Exception( void ); /// constructor
-  Exception( std::exception stdException ); /// constructor
-  Exception( cChar* message ); /// constructor overloaded
-  Exception( String message ); /// constructor overloaded
-  Exception( String message, Int16 lineNo ); /// use __LINE__ @ lineNo
-  Exception( String message, Char* fileName ); /// use __FILE__ @ fileName
-  Exception( String message, Char* fileName, Int16 lineNo ); /// use __FILE__ @ fileName and __LINE__ @ lineNo
-  virtual ~Exception( void ); /// destructor
-
-  String declare( void ) const; /// returns message as std::string
-  void report( void ) const; /// message to console
-  void stop( void ) const; /// message to console and wait for enter
-  void nuke( void ) const; /// do a nuke and melt down afterwards
-
-  friend std::ostream& operator << ( std::ostream& outputStream, Exception& exception ); /// cout
-  friend std::ostream& operator << ( std::ostream& outputStream, Exception* exception ); /// cout
+  /** @brief Default constructor */
+  Exception( void ); 
+  /** @brief Construct from std::exception */
+  Exception( std::exception stdException ); 
+  /** @brief Construct with C-string message */
+  Exception( cChar* message ); 
+  /** @brief Construct with String message */
+  Exception( String message ); 
+  /** @brief Construct with message and line number */
+  Exception( String message, Int16 lineNo ); 
+  /** @brief Construct with message and filename */
+  Exception( String message, Char* fileName ); 
+  /** @brief Construct with message, filename and line number */
+  Exception( String message, Char* fileName, Int16 lineNo ); 
+  /** @brief Destructor */
+  virtual ~Exception( void ); 
+
+  /** @brief Returns the exception message as std::string */
+  String declare( void ) const; 
+  /** @brief Reports the exception message to console */
+  void report( void ) const; 
+  /** @brief Reports to console and waits for user input */
+  void stop( void ) const; 
+  /** @brief Reports and terminates the program */
+  void nuke( void ) const; 
+
+  /** @brief Stream output operator */
+  friend std::ostream& operator << ( std::ostream& outputStream, Exception& exception ); 
+  /** @brief Stream output operator for pointer */
+  friend std::ostream& operator << ( std::ostream& outputStream, Exception* exception ); 
 
  protected:
 
-  String _message; /// the generated exception message
+  /** @brief The exception message */
+  String _message; 
 
  private:
 
-  virtual void mark( void ); /// mark exception
+  /** @brief Marks the exception (internal use) */
+  virtual void mark( void ); 
 
 }; // class Exception