Minor improvements to various documentation comments

Author: mhahnFr

include/callstack.h

@@ -61,19 +61,22 @@ struct callstack {
 /**
  * @brief Creates a callstack of the calling function.
  *
- * The backtrace of the calling function is created.
- * The struct is allocated and needs to be freed using the function `callstack_delete(struct callstack *)`.
- * Returns `NULL` if an error occurs.
+ * The backtrace of the calling function is created.<br>
+ * The returned structure is allocated and needs to be freed using the function
+ * @code callstack_delete(struct callstack *)@endcode.<br>
+ * Returns @c NULL if an error occurs.
  *
  * @return A newly allocated callstack object.
  */
 struct callstack * callstack_new(void);
 
 /**
- * @brief Creates a new callstack object, ignoring all frames after the given address.
+ * @brief Creates a new callstack object, ignoring all frames after the given
+ * address.
  *
- * The struct is allocated and needs to be freed using the function `callstack_delete(struct callstack *)`.
- * Returns `NULL` if an error occurs.
+ * The returned structure is allocated and needs to be freed using the function
+ * @code callstack_delete(struct callstack *)@endcode.<br>
+ * Returns @c NULL if an error occurs.
  *
  * @param address The stack address after which frames are ignored.
  * @return A newly allocated callstack object.
@@ -83,10 +86,12 @@ struct callstack * callstack_newWithAddress(void * address);
 /**
  * @brief Constructs the given callstack object.
  *
- * Stores the backtrace of the calling function.
- * The callstack object needs to be destructed using the function `callstack_destroy(struct callstack *)`
- * upon successful construction and use.
- * If an error occurs during the initialization of the given callstack object, `false` is returned.
+ * Stores the backtrace of the calling function.<br>
+ * The callstack object needs to be destructed using the function
+ * @code callstack_destroy(struct callstack *)@endcode upon successful
+ * construction and use.<br>
+ * If an error occurs during the initialization of the given callstack object,
+ * @c false is returned.
  *
  * @param self A pointer to the callstack object to be constructed.
  * @return Whether the given callstack object was constructed successfully.
@@ -96,9 +101,11 @@ bool callstack_emplace(struct callstack * self);
 /**
  * @brief Constructs the given callstack object.
  *
- * Stores the backtrace of the calling function, ignoring all frames after the given address.
- * The callstack object needs to be destructed using the function `callstack_destroy(struct callstack *)`
- * upon successful construction and use.
+ * Stores the backtrace of the calling function, ignoring all frames after the
+ * given address.<br>
+ * The callstack object needs to be destructed using the function
+ * @code callstack_destroy(struct callstack *)@endcode upon successful
+ * construction and use.
  *
  * @param self A pointer to the callstack object to be constructed.
  * @param address The stack address after which frames are ignored.
@@ -109,12 +116,12 @@ bool callstack_emplaceWithAddress(struct callstack * self, void * address);
 /**
  * @brief Constructs the given callstack object.
  *
- * Copies the given callstack into the given object. If the trace is longer than
- * `CALLSTACK_BACKTRACE_SIZE`, only the first addresses are copied.
- * The callstack object needs to be destructed using the function `callstack_destroy(struct callstack *)`
- * after use.
- * If the given trace length is smaller than zero, `false` is returned and the given callstack
- * is not modified.
+ * Copies the given callstack into the given object. If the trace is longer
+ * than @c CALLSTACK_BACKTRACE_SIZE, only the first addresses are copied.<br>
+ * The callstack object needs to be destructed using the function
+ * @code callstack_destroy(struct callstack *)@endcode after use.<br>
+ * If the given trace length is smaller than zero, @c false is returned and the
+ * given callstack is not modified.
  *
  * @param self A pointer to the callstack object to be constructed.
  * @param trace The backtrace to be copied.
@@ -129,16 +136,16 @@ bool callstack_emplaceWithBacktrace(struct callstack * self,
  *
  * The given callstack is destroyed before the contents of the other one are copied.
  *
- * @param self A pointer to the the callstack to be replaced.
+ * @param self A pointer to the callstack to be replaced.
  * @param other The callstack object to be copied.
  */
 void callstack_copy(struct callstack * self, const struct callstack * other);
 
 /**
  * @brief Translates the given callstack and returns an array of the translated frames.
  *
- * Returns `NULL` if an error happens.
- * Since version `1.1` a `callstack_frame` array is returned.
+ * Returns @c NULL if an error happens.<br>
+ * Since version @c 1.1 a @c callstack_frame array is returned.
  *
  * @param self The callstack object.
  * @return An array of translated callstack frames.
@@ -148,10 +155,10 @@ struct callstack_frame * callstack_toArray(struct callstack * self);
 /**
  * @brief Translates the given callstack and returns an array of the translated frames.
  *
- * If the given callstack has not been translated before, only the binary file information
- * is deducted.
- *
- * Returns `NULL` if an error happens.
+ * If the given callstack has not been translated before, only the binary file
+ * information is deducted.
+ * <br><br>
+ * Returns @c NULL if an error happens.
  *
  * @param self The callstack object.
  * @return An array of translated callstack frames.
@@ -163,14 +170,15 @@ struct callstack_frame * callstack_getBinaries(struct callstack * self);
 /**
  * @brief Translates the given callstack and returns an array of the translated frames.
  *
- * If the given has not been translated before, only the binary file information
- * is deducted.
- *
- * The deducted binary information is located in the cache of the library and becomes
- * invalid after a call to `callstack_clearCaches()` or after the callstack has
- * been translated entirely if `callstack_autoClearCaches` is `true`.
+ * If the given has not been translated before, only the binary file
+ * information is deducted.
  *
- * Returns `NULL` if an error happens.
+ * The deducted binary information is located in the cache of the library and
+ * becomes invalid after a call to @c callstack_clearCaches() or after the
+ * callstack has been translated entirely if @c callstack_autoClearCaches is
+ * @c true .
+ * <br><br>
+ * Returns @c NULL if an error happens.
  *
  * @param self the callstack object
  * @return an array of translated callstack frames

include/callstack_frame.h

@@ -79,7 +79,7 @@ struct callstack_frame {
     bool binaryFileIsSelf;
     /** The line number in the source file this frame is on. */
     unsigned long sourceLine;
-    /** The line column number in the source file.  */
+    /** The line column number in the source file.           */
     unsigned long sourceLineColumn;
 };
 
@@ -107,7 +107,7 @@ static inline void callstack_frame_create(struct callstack_frame * self) {
 /**
  * Allocates a new and initialized callstack frame.
  *
- * @return the allocated callstack frame or `NULL` if unable to allocate
+ * @return the allocated callstack frame or @c NULL if unable to allocate
  * @since v1.1
  */
 static inline struct callstack_frame * callstack_frame_new(void) {
@@ -124,7 +124,7 @@ static inline struct callstack_frame * callstack_frame_new(void) {
  * Allocates a new callstack frame and deeply copies the given callstack frame.
  *
  * @param self the callstack frame to be copied
- * @return a copy of the given callstack frame or `NULL` if unable to allocate
+ * @return a copy of the given callstack frame or @c NULL if unable to allocate
  * @since v1.1
  */
 struct callstack_frame * callstack_frame_copy(const struct callstack_frame * self);
@@ -150,7 +150,8 @@ char * callstack_frame_getShortestName(const struct callstack_frame * self);
 /**
  * @brief Returns the shortest binary file name of the given callstack frame.
  *
- * If the given callstack frame does not have a binary file name the given fallback is returned.
+ * If the given callstack frame does not have a binary file name the given
+ * fallback is returned.
  *
  * @param self the callstack frame
  * @param fallback the fallback string to be returned
@@ -175,7 +176,8 @@ char * callstack_frame_getShortestSourceFile(const struct callstack_frame * self
 /**
  * @brief Returns the shortest source file name of the given callstack frame.
  *
- * If the given callstack frame does not have a source file name the given fallback is returned.
+ * If the given callstack frame does not have a source file name the given
+ * fallback is returned.
  *
  * @param self the callstack frame
  * @param fallback the fallback string to be returned

src/dlMapper/dlMapper.c

@@ -36,7 +36,8 @@ static bool dlMapper_inited = false;
  *
  * @param lhs the left-hand side value
  * @param rhs the right-hand side value
- * @return `0` if the two values compare equal or a value less than or greater than `0` according to the sorting order
+ * @return @c 0 if the two values compare equal or a value less than or greater
+ * than @c 0 according to the sorting order
  */
 static inline int dlMapper_sortCompare(const void* lhs, const void* rhs) {
     const struct loadedLibInfo* a = lhs,
@@ -63,11 +64,13 @@ bool dlMapper_init(void) {
 /**
  * @brief Returns how the given key compares to the given loaded library info.
  *
- * The given key is the searched address, the given element is a loaded library info object.
+ * The given key is the searched address, the given element is a loaded library
+ * info object.
  *
  * @param key the searched key
  * @param element the element to be checked
- * @return `0` if the key is in the loaded library or a value smaller or greater than `0` according to the sorting order
+ * @return @c 0 if the key is in the loaded library or a value smaller or
+ * greater than @c 0 according to the sorting order
  */
 static inline int dlMapper_searchCompare(const void* key, const void* element) {
     // IMPORTANT: key is the searched address, element the array element

src/dlMapper/dlMapper.h

@@ -1,7 +1,7 @@
 /*
  * CallstackLibrary - Library creating human-readable call stacks.
  *
- * Copyright (C) 2024  mhahnFr
+ * Copyright (C) 2024 - 2025  mhahnFr
  *
  * This file is part of the CallstackLibrary.
  *
@@ -30,7 +30,7 @@
  * @brief Initializes the dlMapper.
  *
  * Does nothing if it has already been initialized; if that is the case,
- * `true` will be returned.
+ * @c true will be returned.
  *
  * @return whether the dlMapper has been successfully initialized
  */
@@ -47,15 +47,16 @@ bool dlMapper_isInited(void);
  * Returns the loaded library info the given pointer is associated with.
  *
  * @param address the address whose runtime image to find
- * @return the associated loaded library info object or `NULL` if not in any loaded library
+ * @return the associated loaded library info object or @c NULL if not in any
+ * loaded library
  */
 struct loadedLibInfo* dlMapper_libInfoForAddress(const void* address);
 
 /**
  * Returns the runtime image info for the runtime image of the given name.
  *
  * @param fileName the file name of the runtime image
- * @return the associated runtime image info or `NULL` if not found
+ * @return the associated runtime image info or @c NULL if not found
  */
 struct loadedLibInfo* dlMapper_libInfoForFileName(const char* fileName);
 

src/functionInfo/functionInfo.c

@@ -27,12 +27,14 @@
 #include "../dlMapper/dlMapper.h"
 
 /**
- * Fills the given function info structure using the given loaded runtime image info.
+ * Fills the given function info structure using the given loaded runtime image
+ * info.
  *
  * @param info the runtime image info to be examined
  * @param functionName the name of the function to be found
  * @param functionInfo the function info structure to be filled
- * @return whether the structure was filled, e. g. whether the function was found in the runtime image
+ * @return whether the structure was filled, e.g. whether the function was
+ * found in the runtime image
  */
 static inline bool functionInfo_getFrom(struct loadedLibInfo* info,
                                         const char*           functionName,

src/parser/demangling/cxx/demangler.h

@@ -29,11 +29,11 @@ extern "C" {
 /**
  * @brief Demangles the given name.
  *
- * If the given name is demangled, the given string is not freed.
+ * If the given name is demangled, the given string is not freed.<br>
  * If the name has not been demangled, the given string is returned.
  *
  * @param name The name to be demangled.
- * @return The demangled name or the given name, if it could not be demangled.
+ * @return the demangled name or the given name, if it could not be demangled
  */
 char* callstack_demangle_cxx(char* name);
 

src/parser/demangling/demangler.h

@@ -25,7 +25,7 @@
 /**
  * @brief Attempts to demangle the given name.
  *
- * Currently Swift and C++ demangling is supported.
+ * Currently, Swift and C++ demangling is supported.
  *
  * @param name the name to be demangled
  * @return an allocated demangled name or the input if not mangled

src/parser/file/dwarf/dwarf_lineInfo.h

@@ -29,7 +29,7 @@
 /**
  * @brief This structure represents a source file reference.
  *
- * Unavailable fields are set to `0` and `NULL`, respectively.
+ * Unavailable fields are set to @c 0 and @c NULL, respectively.
  */
 struct dwarf_sourceFile {
     /** The allocated source file name.          */

src/parser/file/dwarf/v4/parser.c

@@ -79,12 +79,14 @@ static inline bool dwarf4_parseLineProgramHeader(struct dwarf_parser* self, size
 }
 
 /**
- * Constructs the full file name for the given file name entry using the given include directories.
+ * Constructs the full file name for the given file name entry using the given
+ * include directories.
  *
  * @param file the file name entry whose full path to construct
  * @param directories the included directories
  * @param defaultDirectory the compilation directory
- * @return an allocated full path string of the given file or `NULL` if the allocation failed or the main source file was referred
+ * @return an allocated full path string of the given file or @c NULL if the
+ * allocation failed or the main source file was referred
  */
 static inline char* dwarf4_stringFrom(const struct dwarf_fileNameEntry* file,
                                       const struct vector_string* directories,
@@ -116,7 +118,8 @@ static inline char* dwarf4_stringFrom(const struct dwarf_fileNameEntry* file,
 /**
  * Constructs a file reference for the given file index.
  *
- * @param self the generified parser object, the specific part for version 4 and earlier is used
+ * @param self the generified parser object, the specific part for version 4
+ * and earlier is used
  * @param file the index of the desired file
  * @return the source file reference
  */

src/parser/file/dwarf/v5/fileAttribute.h

@@ -1,7 +1,7 @@
 /*
  * CallstackLibrary - Library creating human-readable call stacks.
  *
- * Copyright (C) 2024  mhahnFr
+ * Copyright (C) 2024 - 2025  mhahnFr
  *
  * This file is part of the CallstackLibrary.
  *
@@ -27,7 +27,7 @@
 /**
  * @brief This structure represents a DWARF 5 file attribute.
  *
- * Unavailable fields are set to `0` and `NULL`, respectively.
+ * Unavailable fields are set to @c 0 and @c NULL, respectively.
  */
 struct fileAttribute {
     /** The path name.                          */