Improved Code Documentation (#771)

* comments to doxygen

* some more descriptions

* Overhauled README.dox

* Added texts + fixed typos

* More descriptions and typo fixes

* Revert change in LLVM code

* Fix existing docs

* Some more comments + update Doxyfile.in

* Add gh-pages deploy script

* pre-commit

* Small compiler fix

* pre-commit with newer clang version

* install Doxygen in CI

* test

* add token

* Remove gh-pages deploy trigger on pull-request

* install graphviz in CI to draw pretty class diagrams

* update website

* Remove gh-pages deploy trigger on pull-request

* Apply review comments

---------

Co-authored-by: mxHuber <[email protected]>

Author: fabianbs96

.github/workflows/deploy-docs.yml

@@ -0,0 +1,41 @@
+name: Build and Deploy Doxygen Docs
+on:
+  push:
+    branches: [ development ]
+  # pull_request: # For testing only.  Remove before merge!
+  #   branches: [ development ]
+permissions:
+  contents: write
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: true
+    continue-on-error: false
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: recursive
+
+      - name: Install Phasar Dependencies
+        shell: bash
+        run: |
+          ./utils/InstallAptDependencies.sh --noninteractive tzdata doxygen graphviz
+
+      - name: Build Doxygen Docs
+        shell: bash
+        env:
+          CXX: clang++-15
+          CC: clang-15
+        run: |
+           cmake -S . -B build -DPHASAR_BUILD_DOC=ON
+           cmake --build ./build --target doc_doxygen
+
+      - name: Deploy Doxygen Docs on GitHub Pages
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: build/docs/html
+          token: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -25,7 +25,7 @@ Currently, PhASAR is maintained by
 PhASAR requires at least C++-17.
 
 However, building in C++20 mode is supported. You may enable this setting the cmake variable `CMAKE_CXX_STANDARD` to `20`.
-Although phasar currently does not make use of C++-20 features (except for some `concept`s behind an #ifdef border), your client application that just *uses* phasar as a library may want to use C++20 ealier.
+Although phasar currently does not make use of C++-20 features (except for some `concept`s behind an #ifdef border), your client application that just *uses* phasar as a library may want to use C++20 earlier.
 
 ## Currently Supported Version of LLVM
 

docs/Doxyfile.in

@@ -32,19 +32,19 @@ DOXYFILE_ENCODING      = UTF-8
 # title of most generated pages and in a few other places.
 # The default value is: My Project.
 
-PROJECT_NAME           = "PhASAR"
+PROJECT_NAME           = PhASAR
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. This
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = @PHASAR_VERSION@
+PROJECT_NUMBER         = @PHASAR_VERSION@@development
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
 # quick idea about the purpose of the project. Keep the description short.
 
-PROJECT_BRIEF          = "PhASAR a LLVM-based Static Analysis Framework"
+PROJECT_BRIEF          = "A LLVM-based Static Analysis Framework"
 
 # With the PROJECT_LOGO tag one can specify an logo or icon that is included in
 # the documentation. The maximum height of the logo should not exceed 55 pixels
@@ -144,7 +144,7 @@ FULL_PATH_NAMES        = YES
 # will be relative from the directory where doxygen is started.
 # This tag requires that the tag FULL_PATH_NAMES is set to YES.
 
-STRIP_FROM_PATH        =
+STRIP_FROM_PATH        = @PHASAR_SRC_DIR@
 
 # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the
 # path mentioned in the documentation of a class, which tells the reader which
@@ -153,8 +153,7 @@ STRIP_FROM_PATH        =
 # specify the list of include paths that are normally passed to the compiler
 # using the -I flag.
 
-STRIP_FROM_INC_PATH    =
-
+STRIP_FROM_INC_PATH    = @PHASAR_SRC_DIR@/include
 # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but
 # less readable) file names. This can be useful is your file systems doesn't
 # support long names like on DOS, Mac, or CD-ROM.
@@ -398,7 +397,7 @@ LOOKUP_CACHE_SIZE      = 0
 # normally produced when WARNINGS is set to YES.
 # The default value is: NO.
 
-EXTRACT_ALL            = NO
+EXTRACT_ALL            = YES
 
 # If the EXTRACT_PRIVATE tag is set to YES all private members of a class will
 # be included in the documentation.
@@ -743,7 +742,8 @@ WARN_LOGFILE           =
 # spaces.
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/include/ @CMAKE_CURRENT_SOURCE_DIR@/lib/ @CMAKE_CURRENT_SOURCE_DIR@/docs
+INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/include/ \
+                         @CMAKE_CURRENT_SOURCE_DIR@/docs
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -794,7 +794,7 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       =
+EXCLUDE_PATTERNS       = */external/*
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
@@ -805,7 +805,7 @@ EXCLUDE_PATTERNS       =
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories use the pattern */test/*
 
-EXCLUDE_SYMBOLS        =
+EXCLUDE_SYMBOLS        = *::detail::*
 
 # The EXAMPLE_PATH tag can be used to specify one or more files or directories
 # that contain example code fragments that are included (see the \include
@@ -905,7 +905,7 @@ INLINE_SOURCES         = NO
 # Fortran comments will always remain visible.
 # The default value is: YES.
 
-STRIP_CODE_COMMENTS    = YES
+STRIP_CODE_COMMENTS    = NO
 
 # If the REFERENCED_BY_RELATION tag is set to YES then for each documented
 # function all documented functions referencing it will be listed.
@@ -917,7 +917,7 @@ REFERENCED_BY_RELATION = YES
 # all documented entities called/used by that function will be listed.
 # The default value is: NO.
 
-REFERENCES_RELATION    = NO
+REFERENCES_RELATION    = YES
 
 # If the REFERENCES_LINK_SOURCE tag is set to YES and SOURCE_BROWSER tag is set
 # to YES, then the hyperlinks from functions in REFERENCES_RELATION and
@@ -1407,7 +1407,7 @@ FORMULA_TRANSPARENT    = YES
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-USE_MATHJAX            = NO
+USE_MATHJAX            = YES
 
 # When MathJax is enabled you can set the default output format to be used for
 # the MathJax output. See the MathJax site (see:
@@ -1521,7 +1521,7 @@ SEARCHDATA_FILE        = searchdata.xml
 # projects and redirect the results back to the right project.
 # This tag requires that the tag SEARCHENGINE is set to YES.
 
-EXTERNAL_SEARCH_ID     =
+EXTERNAL_SEARCH_ID     = phasar
 
 # The EXTRA_SEARCH_MAPPINGS tag can be used to enable searching through doxygen
 # projects other than the one defined by this configuration file, but that are
@@ -1540,7 +1540,7 @@ EXTRA_SEARCH_MAPPINGS  =
 # If the GENERATE_LATEX tag is set to YES doxygen will generate LaTeX output.
 # The default value is: YES.
 
-GENERATE_LATEX         = YES
+GENERATE_LATEX         = NO
 
 # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
@@ -1917,7 +1917,7 @@ SEARCH_INCLUDES        = YES
 # preprocessor.
 # This tag requires that the tag SEARCH_INCLUDES is set to YES.
 
-INCLUDE_PATH           =
+INCLUDE_PATH           = @PHASAR_BINARY_DIR@/include
 
 # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
 # patterns (like *.h and *.hpp) to filter out the header-files in the
@@ -2040,7 +2040,7 @@ DIA_PATH               =
 # and usage relations if the target is undocumented or is not a class.
 # The default value is: YES.
 
-HIDE_UNDOC_RELATIONS   = YES
+HIDE_UNDOC_RELATIONS   = NO
 
 # If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is
 # available from the path. This tool is part of Graphviz (see:
@@ -2100,7 +2100,7 @@ CLASS_GRAPH            = YES
 # The default value is: YES.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-COLLABORATION_GRAPH    = YES
+COLLABORATION_GRAPH    = NO
 
 # If the GROUP_GRAPHS tag is set to YES then doxygen will generate a graph for
 # groups, showing the direct groups dependencies.
@@ -2136,7 +2136,7 @@ UML_LIMIT_NUM_FIELDS   = 10
 # The default value is: NO.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-TEMPLATE_RELATIONS     = NO
+TEMPLATE_RELATIONS     = YES
 
 # If the INCLUDE_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are set to
 # YES then doxygen will generate a graph for each documented file showing the
@@ -2145,7 +2145,7 @@ TEMPLATE_RELATIONS     = NO
 # The default value is: YES.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-INCLUDE_GRAPH          = YES
+INCLUDE_GRAPH          = NO
 
 # If the INCLUDED_BY_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are
 # set to YES then doxygen will generate a graph for each documented file showing
@@ -2154,7 +2154,7 @@ INCLUDE_GRAPH          = YES
 # The default value is: YES.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-INCLUDED_BY_GRAPH      = YES
+INCLUDED_BY_GRAPH      = NO
 
 # If the CALL_GRAPH tag is set to YES then doxygen will generate a call
 # dependency graph for every global function or class method.
@@ -2203,7 +2203,7 @@ DIRECTORY_GRAPH        = YES
 # The default value is: png.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOT_IMAGE_FORMAT       = png
+DOT_IMAGE_FORMAT       = svg
 
 # If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to
 # enable generation of interactive SVG images that allow zooming and panning.
@@ -2276,7 +2276,7 @@ MAX_DOT_GRAPH_DEPTH    = 0
 # The default value is: NO.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOT_TRANSPARENT        = NO
+DOT_TRANSPARENT        = YES
 
 # Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output
 # files in one run (i.e. multiple -o and -T options on the command line). This

docs/README.dox

@@ -2,14 +2,27 @@
 
 @mainpage PhASAR: A LLVM-based Static Analysis Framework
 
-@author Philipp Schubert (E-Mail: [email protected]) and others
+PhASAR is a LLVM-based static analysis framework written in C++. It allows users to specify arbitrary data-flow problems which are then solved in a fully-automated manner on the specified LLVM IR target code. Computing points-to information, call-graph(s), etc. is done by the framework, thus you can focus on what matters.
 
-\b Copyright \n
-	Copyright 2017 Philipp Schubert. All rights reserved.
+This page contains the generated code documentation of PhASAR.
+You can find the original source on GitHub: <https://github.com/secure-software-engineering/phasar>. The README should already give you a good first overview.
 
-\b License \n
-	See LICENSE.txt
+For further information, please checkout PhASAR's [Wiki](https://github.com/secure-software-engineering/phasar/wiki).
+
+@subsubsection SSEG Secure Software Engineering Group
+
+PhASAR is primarily developed and maintained by the [Secure Software Engineering Group](https://www.hni.uni-paderborn.de/sse) at Heinz Nixdorf Institute (University of Paderborn) and [Fraunhofer IEM](https://www.iem.fraunhofer.de/).
 
-TODO: add detailed description.
+PhASAR was initially developed by Philipp Dominik Schubert (<a href="https://github.com/pdschubert">@pdschubert</a>)(<[email protected]>).
+
+\b Currently, PhASAR is maintained by
+- Fabian Schiebel (<a href="https://github.com/fabianbs96">@fabianbs96</a>)([email protected])
+- Sriteja Kummita (<a href="https://github.com/sritejakv">@sritejakv</a>)
+- Lucas Briese (<a href="https://github.com/jusito">@jusito</a>)
+- Martin Mory (<a href="https://github.com/MMory">@MMory</a>)([email protected])
+- *others*
+
+\b License \n
+	PhASAR is made available under the permissive MIT License. See <a href="https://github.com/secure-software-engineering/phasar/blob/development/LICENSE.txt">LICENSE.txt</a>
 
 */

include/phasar/AnalysisStrategy/AnalysisSetup.h

@@ -16,7 +16,7 @@
 
 namespace psr {
 
-// Indicates that an analysis does not need a special configuration (file).
+/// Indicates that an analysis does not need a special configuration (file).
 struct HasNoConfigurationType {};
 
 struct AnalysisSetup {

include/phasar/ControlFlow/CallGraphData.h

@@ -18,8 +18,12 @@
 #include <vector>
 
 namespace psr {
+
+/// A data structure used for storing, serializing and deserializing call-graph
+/// information.
 struct CallGraphData {
-  // Mangled FunName --> [CS-IDs]
+
+  /// Mangled FunName --> [CS-IDs]
   std::unordered_map<std::string, std::vector<uint32_t>> FToFunctionVertexTy{};
 
   CallGraphData() noexcept = default;

include/phasar/ControlFlow/ICFGBase.h

@@ -36,7 +36,7 @@ template <typename Derived> class ICFGBase : public CRTPBase<Derived> {
   }
 
   /// returns the function definition or declaration with the given name. If
-  /// ther eis no such function, returns a default constructed f_t (nullptr for
+  /// there is no such function, returns a default constructed f_t (nullptr for
   /// pointers).
   [[nodiscard]] f_t getFunction(llvm::StringRef Fun) const {
     return self().getFunctionImpl(Fun);

include/phasar/DB/ProjectIRDBBase.h

@@ -24,7 +24,7 @@ template <typename DB> struct ProjectIRDBTraits {
   // using g_t
 };
 
-/// This class owns the IR code of the project under analysis and some
+/// This class owns the IR code of the target being analyzed and some
 /// very important information associated with the IR.
 /// When an object of this class is destroyed it will clean up all IR related
 /// stuff that is stored in it.

include/phasar/DataFlow/IfdsIde/EdgeFunction.h

@@ -65,7 +65,7 @@ concept IsEdgeFunction = requires(const T &EF, const EdgeFunction<typename T::l_
   {T::compose(CEF, TEEF)}  -> std::same_as<EdgeFunction<typename T::l_t>>;
   {T::join(CEF, TEEF)}     -> std::same_as<EdgeFunction<typename T::l_t>>;
 };
-  // clang-format on
+// clang-format on
 
 #endif
 
@@ -78,18 +78,20 @@ enum class EdgeFunctionAllocationPolicy {
 class EdgeFunctionBase {
 public:
   template <typename ConcreteEF>
-  static constexpr bool
-      IsSOOCandidate = sizeof(ConcreteEF) <= sizeof(void *) && // NOLINT
-                       alignof(ConcreteEF) <= alignof(void *) &&
-                       std::is_trivially_copyable_v<ConcreteEF>;
+  static constexpr bool IsSOOCandidate =
+      sizeof(ConcreteEF) <= sizeof(void *) && // NOLINT
+      alignof(ConcreteEF) <= alignof(void *) &&
+      std::is_trivially_copyable_v<ConcreteEF>;
 
   using AllocationPolicy = EdgeFunctionAllocationPolicy;
 
 protected:
   struct RefCountedBase {
     mutable std::atomic_size_t Rc = 0;
   };
-  template <typename T> struct RefCounted : RefCountedBase { T Value; };
+  template <typename T> struct RefCounted : RefCountedBase {
+    T Value;
+  };
 
   template <typename T> struct CachedRefCounted : RefCounted<T> {
     EdgeFunctionSingletonCache<T> *Cache{};
@@ -118,8 +120,8 @@ class EdgeFunctionBase {
                                  : AllocationPolicy::CustomHeapAllocated;
 };
 
-/// Non-null reference to an edge function that is guarenteed to be managed by
-/// an EdgeFunction object.
+/// \brief Non-null reference to an edge function that is guarenteed to be
+/// managed by an EdgeFunction object.
 template <typename EF>
 class [[clang::trivial_abi]] EdgeFunctionRef final : EdgeFunctionBase {
   template <typename L> friend class EdgeFunction;
@@ -164,8 +166,8 @@ class [[clang::trivial_abi]] EdgeFunctionRef final : EdgeFunctionBase {
       IsCached{};
 };
 
-/// Ref-counted and type-erased edge function with small-object optimization.
-/// Supports caching.
+/// \brief Ref-counted and type-erased edge function with small-object
+/// optimization. Supports caching.
 template <typename L>
 // -- combined copy and move assignment
 // NOLINTNEXTLINE(cppcoreguidelines-special-member-functions)
@@ -265,8 +267,8 @@ class [[clang::trivial_abi]] EdgeFunction final : EdgeFunctionBase {
   explicit EdgeFunction(
       std::in_place_type_t<ConcreteEF> /*unused*/,
       ArgTys &&...Args) noexcept(IsSOOCandidate<std::decay_t<ConcreteEF>> &&
-                                     std::is_nothrow_constructible_v<ConcreteEF,
-                                                                     ArgTys...>)
+                                 std::is_nothrow_constructible_v<ConcreteEF,
+                                                                 ArgTys...>)
       : EdgeFunction(
             [](auto &&...Args) {
               if constexpr (IsSOOCandidate<std::decay_t<ConcreteEF>>) {