Improve doxygen docs (#819)

Author: fabianbs96

docs/Doxyfile.in

@@ -763,7 +763,7 @@ INPUT_ENCODING         = UTF-8
 # *.md, *.mm, *.dox, *.py, *.f90, *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf,
 # *.qsf, *.as and *.js.
 
-FILE_PATTERNS          = *.dox *.c *.h *.cpp *.hh *.cu *.cuh
+FILE_PATTERNS          = *.dox *.c *.h *.def *.cpp *.hh *.cu *.cuh
 
 # The RECURSIVE tag can be used to specify whether or not subdirectories should
 # be searched for input files as well.
@@ -1895,15 +1895,15 @@ ENABLE_PREPROCESSING   = YES
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
 # the macro expansion is limited to the macros specified with the PREDEFINED and
 # EXPAND_AS_DEFINED tags.
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-EXPAND_ONLY_PREDEF     = NO
+EXPAND_ONLY_PREDEF     = YES
 
 # If the SEARCH_INCLUDES tag is set to YES the includes files in the
 # INCLUDE_PATH will be searched if a #include is found.
@@ -1944,7 +1944,7 @@ PREDEFINED             =
 # definition found in the source code.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-EXPAND_AS_DEFINED      =
+EXPAND_AS_DEFINED      = DATA_FLOW_ANALYSIS_TYPES ANALYSIS_STRATEGY_TYPES CALL_GRAPH_ANALYSIS_TYPE ALIAS_ANALYSIS_TYPE ALIAS_RESULT_TYPE  SEVERITY_LEVEL SPECIAL_MEMBER_FUNCTION_TYPES  SOUNDNESS_FLAG_TYPE
 
 # If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will
 # remove all refrences to function-like macros that are alone on a line, have an
@@ -1954,7 +1954,7 @@ EXPAND_AS_DEFINED      =
 # The default value is: YES.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-SKIP_FUNCTION_MACROS   = YES
+SKIP_FUNCTION_MACROS   = NO
 
 #---------------------------------------------------------------------------
 # Configuration options related to external references

include/phasar/DataFlow/IfdsIde/IFDSTabulationProblem.h

@@ -55,7 +55,6 @@ class IFDSTabulationProblem
   /// `"__ALL__"`
   /// @param[in] ZeroValue Provides the special tautological zero value (aka.
   /// Λ).
-  /// \endlink.
   explicit IFDSTabulationProblem(const db_t *IRDB,
                                  std::vector<std::string> EntryPoints,
                                  d_t ZeroValue)

include/phasar/PhasarLLVM/DataFlow/IfdsIde/CFLFieldSensIFDSProblem.h

@@ -39,7 +39,8 @@
 
 namespace psr::cfl_fieldsens {
 
-/// \file Implements field-sensitivity after the paper "Boosting the performance
+/// \file
+/// Implements field-sensitivity after the paper "Boosting the performance
 /// of alias-aware IFDS analysis with CFL-based environment transformers" by Li
 /// et al. <https://doi.org/10.1145/3689804>
 

include/phasar/PhasarLLVM/Utils/Annotation.h

@@ -10,7 +10,8 @@
 
 namespace psr {
 
-/// \file Helper classes that allow for an easier retrieval of annotation
+/// \file
+/// Helper classes that allow for an easier retrieval of annotation
 /// information.
 
 class VarAnnotation {

include/phasar/PhasarLLVM/Utils/LLVMIRToSrc.h

@@ -39,7 +39,8 @@ class DILocation;
 
 namespace psr {
 
-/// \file This file contains useful structs and functions to get and store
+/// \file
+/// This file contains useful structs and functions to get and store
 /// information about the source code or the intermediate representation of the
 /// target being analyzed.
 

include/phasar/PhasarLLVM/Utils/LLVMShorthands.h

@@ -84,14 +84,14 @@ llvm::ModuleSlotTracker &getModuleSlotTrackerFor(const llvm::Value *V);
 [[nodiscard]] std::string llvmIRToString(const llvm::Value *V);
 
 /**
- * @brief Similar to llvmIRToString, but removes the metadata from the output as
- * they are not always stable. Prefer this function over llvmIRToString, if you
- * are comparing the string representations of LLVM iR instructions.
+ * @brief Similar to llvmIRToString(), but removes the metadata from the output
+ * as they are not always stable. Prefer this function over llvmIRToString, if
+ * you are comparing the string representations of LLVM iR instructions.
  */
 [[nodiscard]] std::string llvmIRToStableString(const llvm::Value *V);
 
 /**
- * @brief Same as @link(llvmIRToString) but tries to shorten the
+ * @brief Same as llvmIRToString() but tries to shorten the
  *        resulting string
  */
 std::string llvmIRToShortString(const llvm::Value *V);
@@ -129,7 +129,7 @@ globalValuesUsedinFunction(const llvm::Function *F);
  * Only Instructions and GlobalVariables have 'real' ID's, i.e. annotated meta
  * data. Formal arguments cannot be annotated with metadata in LLVM. Therefore,
  * a formal arguments ID will look like this:
- *    <function_name>.<#argument>
+ *    `<function_name>.<#argument>`
  *
  * ZeroValue will have -1 as ID by default.
  *
@@ -161,7 +161,7 @@ int getFunctionArgumentNr(const llvm::Argument *Arg);
  *
  * @brief Returns the n-th LLVM Argument of a given LLVM Function.
  * @param F Function to retrieve the Arguments from.
- * @param argNo Argument number.
+ * @param ArgNo Argument number.
  * @return LLVM Argument or nullptr, if argNo invalid.
  */
 const llvm::Argument *getNthFunctionArgument(const llvm::Function *F,
@@ -172,7 +172,7 @@ const llvm::Argument *getNthFunctionArgument(const llvm::Function *F,
  *
  * @brief Returns the n-th LLVM Instruction of a given LLVM Function.
  * @param F Function to retrieve the Instruction from.
- * @param instNo Instruction number.
+ * @param Idx Instruction number.
  * @return LLVM Instruction or nullptr, if instNo invalid.
  */
 const llvm::Instruction *getNthInstruction(const llvm::Function *F,
@@ -187,7 +187,7 @@ const llvm::Instruction *getLastInstructionOf(const llvm::Function *F);
  * @brief Returns the n-th LLVM Termination Instruction of a given LLVM
  * Function.
  * @param F Function to retrieve the Termination Instruction from.
- * @param termInstNo Termination Instruction number.
+ * @param TermInstNo Termination Instruction number.
  * @return LLVM Instruction or nullptr, if termInstNo invalid.
  */
 const llvm::Instruction *getNthTermInstruction(const llvm::Function *F,
@@ -199,7 +199,7 @@ const llvm::Instruction *getNthTermInstruction(const llvm::Function *F,
  * @brief Returns the n-th LLVM Store Instruction of a given LLVM
  * Function.
  * @param F Function to retrieve the Store Instruction from.
- * @param termInstNo Store Instruction number.
+ * @param TermInstNo Store Instruction number.
  * @return LLVM Store Instruction or nullptr, if stoNo invalid.
  */
 const llvm::StoreInst *getNthStoreInstruction(const llvm::Function *F,
@@ -230,7 +230,7 @@ std::string getModuleNameFromVal(const llvm::Value *V);
 /**
  * @brief Computes a hash value for a given LLVM Module.
  * @param M LLVM Module.
- * @param considerIdentifier If true, module identifier will be considered for
+ * @param ConsiderIdentifier If true, module identifier will be considered for
  * hash computation.
  * @return Hash value.
  */

include/phasar/Utils/DebugOutput.h

@@ -23,7 +23,8 @@
 namespace psr {
 namespace detail {
 
-/// \file This file contains many useful ways of printing information for
+/// \file
+/// This file contains many useful ways of printing information for
 /// debugging purposes.
 
 template <typename OS_t, typename T> void printHelper(OS_t &OS, const T &Data);

include/phasar/Utils/ErrorHandling.h

@@ -19,7 +19,8 @@
 
 namespace psr {
 
-/// \file This file contains useful functions for handling errors, by using
+/// \file
+/// This file contains useful functions for handling errors, by using
 /// std::system_error, or returning null or a default value.
 
 template <typename T> T getOrThrow(llvm::ErrorOr<T> ValOrErr) {

include/phasar/Utils/IO.h

@@ -28,7 +28,8 @@
 
 namespace psr {
 
-/// \file This file contains functions for reading in text files and json files
+/// \file
+/// This file contains functions for reading in text files and json files
 /// and provides error handling capabilities as well, if needed.
 
 [[nodiscard]] llvm::ErrorOr<std::string>

include/phasar/Utils/MemoryResource.h

@@ -1,5 +1,5 @@
-/// On some MAC systems, <memory_resource> is still not fully implemented, so do
-/// a workaround here
+/// On some MAC systems, `<memory_resource>` is still not fully implemented, so
+/// do a workaround here
 
 #ifndef HAS_MEMORY_RESOURCE
 #if !defined(__has_include) || __has_include(<memory_resource>)