[refactor, WIP] Added docs for Location-related entities.

Author: S1eGa

include/klee/Module/LocationInfo.h

@@ -22,6 +22,10 @@ class Instruction;
 class Module;
 } // namespace llvm
 
+namespace klee {
+struct PhysicalLocationJson;
+}
+
 namespace klee {
 
 /// @brief Immutable struct representing location in source code.
@@ -34,6 +38,12 @@ struct LocationInfo {
 
   /// @brief Column number in source file.
   const std::optional<uint64_t> column;
+
+  /// @brief Converts location info to SARIFs representation
+  /// of location.
+  /// @param location location info in source code.
+  /// @return SARIFs representation of location.
+  PhysicalLocationJson serialize() const;
 };
 
 LocationInfo getLocationInfo(const llvm::Function *func);

lib/Core/CMakeLists.txt

@@ -15,7 +15,7 @@ add_library(kleeCore
   CoreStats.cpp
   CXXTypeSystem/CXXTypeManager.cpp
   DistanceCalculator.cpp
-  EventList.cpp
+  EventRecorder.cpp
   ExecutionState.cpp
   Executor.cpp
   ExecutorUtil.cpp

lib/Core/CodeEvent.h

@@ -29,13 +29,11 @@ class CodeEvent {
       : kind(kind), location(location) {}
 
   /// @brief Additional info to current event.
-  /// @returns string describing event.
+  /// @return String describing event.
   virtual std::string description() const = 0;
 
-  // FIXME: compelte the docs.
-  /// @brief
-  /// @param event
-  /// @return
+  /// @brief Serialize event to the JSON format.
+  /// @return JSON object describing event.
   LocationJson serialize() const {
     LocationJson result;
 
@@ -45,6 +43,8 @@ class CodeEvent {
     return result;
   }
 
+  /// @brief Kind of event used for LLVM RTTI.
+  /// @return Kind of event.
   EventKind getKind() const { return kind; }
 
   virtual ~CodeEvent() = default;

lib/Core/CodeLocation.cpp

@@ -1,30 +1,41 @@
 #include "CodeLocation.h"
 
+#include "klee/ADT/Ref.h"
 #include "klee/Module/LocationInfo.h"
 #include "klee/Module/SarifReport.h"
 
+#include <cinttypes>
 #include <optional>
+#include <string>
 #include <utility>
 
 using namespace klee;
 
-/// @brief Converts location info to SARIFs representation
-/// of location.
-/// @param location location info in source code.
-/// @return SARIFs representation of location.
-static PhysicalLocationJson from(const LocationInfo &location) {
-  // Clang-format does not keep pretty format for JSON.
-  // For better readability split creating of JSON in local variables.
-
-  ArtifactLocationJson artifactLocationJson{{location.file}};
-  RegionJson regionJson{
-      {location.line}, std::nullopt, location.column, std::nullopt};
-  PhysicalLocationJson physicalLocationJson{{std::move(artifactLocationJson)},
-                                            {std::move(regionJson)}};
+CodeLocation::CodeLocation(const Path::PathIndex &pathIndex,
+                           const KValue *source,
+                           const std::string &sourceFilename,
+                           uint64_t sourceCodeLine,
+                           std::optional<uint64_t> sourceCodeColumn)
+    : pathIndex(pathIndex), source(source),
+      location(LocationInfo{sourceFilename, sourceCodeLine, sourceCodeColumn}) {
+}
 
-  return physicalLocationJson;
+ref<CodeLocation>
+CodeLocation::create(const Path::PathIndex &pathIndex, const KValue *source,
+                     const std::string &sourceFilename, uint64_t sourceCodeLine,
+                     std::optional<uint64_t> sourceCodeColumn = std::nullopt) {
+  return new CodeLocation(pathIndex, source, sourceFilename, sourceCodeLine,
+                          sourceCodeColumn);
 }
 
-////////////////////////////////////////////////////////////////
+ref<CodeLocation>
+CodeLocation::create(const KValue *source, const std::string &sourceFilename,
+                     uint64_t sourceCodeLine,
+                     std::optional<uint64_t> sourceCodeColumn = std::nullopt) {
+  return new CodeLocation(Path::PathIndex{0, 0}, source, sourceFilename,
+                          sourceCodeLine, sourceCodeColumn);
+}
 
-PhysicalLocationJson CodeLocation::serialize() const { return from(location); }
+PhysicalLocationJson CodeLocation::serialize() const {
+  return location.serialize();
+}

lib/Core/CodeLocation.h

@@ -5,6 +5,7 @@
 #include "klee/Expr/Path.h"
 #include "klee/Module/LocationInfo.h"
 
+#include <cinttypes>
 #include <cstdint>
 #include <iostream>
 #include <optional>
@@ -33,41 +34,35 @@ struct CodeLocation {
 private:
   CodeLocation(const Path::PathIndex &pathIndex, const KValue *source,
                const std::string &sourceFilename, uint64_t sourceCodeLine,
-               std::optional<uint64_t> sourceCodeColumn)
-      : pathIndex(pathIndex), source(source),
-        location(
-            LocationInfo{sourceFilename, sourceCodeLine, sourceCodeColumn}) {}
+               std::optional<uint64_t> sourceCodeColumn);
 
   CodeLocation(const CodeLocation &) = delete;
   CodeLocation &operator=(const CodeLocation &) = delete;
 
 public:
-  /// @brief: Factory method. Wraps constructed objects in the ref
-  /// to provide zero-cost copying of code locations.
-  /// @param sourceFilename
-  /// @param sourceCodeLine
-  /// @param sourceCodeColumn
-  /// @return
-  static ref<CodeLocation>
-  create(const Path::PathIndex &pathIndex, const KValue *source,
-         const std::string &sourceFilename, uint64_t sourceCodeLine,
-         std::optional<uint64_t> sourceCodeColumn = std::nullopt) {
-    return new CodeLocation(pathIndex, source, sourceFilename, sourceCodeLine,
-                            sourceCodeColumn);
-  }
+  /// @brief Factory method for `CodeLocation` enhanced with `PathIndex`
+  /// in history. Wraps constructed objects in the ref to provide
+  /// zero-cost copying of code locations.
+  /// @param sourceFilename Name of source file to which location refers.
+  /// @param sourceCodeLine Line in source to which location refers.
+  /// @param sourceCodeColumn Column in source code to which location refers.
+  /// @return `CodeLocation` representing the location in source code.
+  static ref<CodeLocation> create(const Path::PathIndex &pathIndex,
+                                  const KValue *source,
+                                  const std::string &sourceFilename,
+                                  uint64_t sourceCodeLine,
+                                  std::optional<uint64_t> sourceCodeColumn);
 
-  /// @brief TODO: finish docs.
-  /// @param sourceFilename
-  /// @param sourceCodeLine
-  /// @param sourceCodeColumn
-  /// @return
-  static ref<CodeLocation>
-  create(const KValue *source, const std::string &sourceFilename,
-         uint64_t sourceCodeLine,
-         std::optional<uint64_t> sourceCodeColumn = std::nullopt) {
-    return new CodeLocation(Path::PathIndex{0, 0}, source, sourceFilename,
-                            sourceCodeLine, sourceCodeColumn);
-  }
+  /// @brief Factory method for `CodeLocation`. Wraps constructed
+  /// objects in the ref to provide zero-cost copying of code locations.
+  /// @param sourceFilename Name of source file to which location refers.
+  /// @param sourceCodeLine Line in source to which location refers.
+  /// @param sourceCodeColumn Column in source code to which location refers.
+  /// @return `CodeLocation` representing the location in source code.
+  static ref<CodeLocation> create(const KValue *source,
+                                  const std::string &sourceFilename,
+                                  uint64_t sourceCodeLine,
+                                  std::optional<uint64_t> sourceCodeColumn);
 
   /// @brief Converts code location info to SARIFs representation
   /// of location.

lib/Core/EventList.cpp lib/Core/EventRecorder.cpplib/Core/EventList.cpp renamed to lib/Core/EventRecorder.cpp

@@ -1,4 +1,4 @@
-#include "EventList.h"
+#include "EventRecorder.h"
 #include "CodeEvent.h"
 
 #include "klee/ADT/ImmutableList.h"
@@ -60,6 +60,7 @@ EventRecorder EventRecorder::inRange(const Path::PathIndex &begin,
   }
 
   // TODO: not effective.
+  /// FIXME:
   for (const auto &event : events) {
     const Path::PathIndex &eventPathIndex = event->location->pathIndex;
     if (!Path::PathIndexCompare{}(eventPathIndex, begin) &&

lib/Core/EventList.h lib/Core/EventRecorder.hlib/Core/EventList.h renamed to lib/Core/EventRecorder.h

@@ -1,5 +1,5 @@
-#ifndef KLEE_EVENT_LIST_H
-#define KLEE_EVENT_LIST_H
+#ifndef KLEE_EVENT_RECORDER_H
+#define KLEE_EVENT_RECORDER_H
 
 #include "klee/Expr/Path.h"
 
@@ -28,36 +28,37 @@ class EventRecorder {
   /// @param event event to record.
   void record(const ref<CodeEvent> &event);
 
-  /// @brief
-  /// @param rhs
+  /// @brief Appends all events from the given `EventRecorder`
+  /// to this recorder.
+  /// @param rhs `EventRecorder` to get events from.
   void append(const EventRecorder &rhs);
 
   /// @brief Returns events from the history in specified range.
   /// @param begin range begin.
   /// @param end range end.
-  /// @return immutable list containing recorder events from inner storage.
+  /// @return `EventRecorder` containing recorder events from inner storage.
   EventRecorder inRange(const Path::PathIndex &begin,
                         const Path::PathIndex &end) const;
 
   /// @brief Returns events from the history from the givent event.
   /// @param begin range begin.
-  /// @return immutable list containing recorder events from inner storage.
+  /// @return `EventRecorder` containing recorder events from inner storage.
   EventRecorder tail(const Path::PathIndex &begin) const;
 
-  /// @brief
-  /// @return
+  /// @brief Returns last recorder event.
+  /// @return Last recorded `CodeEvent`.
   ref<CodeEvent> last() const;
 
-  /// @brief
-  /// @return
+  /// @brief Tests whether this event recorder is empty.
+  /// @return `true` if there are no events have been recorded.
   bool empty() const;
 
-  /// @brief Serializes events in this recorder to SARIF report.
+  /// @brief Serializes events in this recorder to SARIF format.
   /// @return Structure ready for wrapping into json
   /// (i.e. `json(serialize())`) and serialization.
   CodeFlowJson serialize() const;
 };
 
 } // namespace klee
 
-#endif // KLEE_EVENT_LIST_H
+#endif // KLEE_EVENT_RECORDER_H

lib/Core/ExecutionState.h

@@ -32,7 +32,7 @@
 #include "klee/Utilities/Math.h"
 
 #include "CodeLocation.h"
-#include "EventList.h"
+#include "EventRecorder.h"
 
 #include "klee/Support/CompilerWarning.h"
 DISABLE_WARNING_PUSH

lib/Core/Executor.cpp

@@ -78,7 +78,7 @@
 #include "CodeEvents/ErrorEvent.h"
 #include "CodeEvents/ReturnEvent.h"
 #include "CodeLocation.h"
-#include "EventList.h"
+#include "EventRecorder.h"
 
 #include "klee/Support/CompilerWarning.h"
 DISABLE_WARNING_PUSH

lib/Module/LocationInfo.cpp

@@ -8,8 +8,9 @@
 //===----------------------------------------------------------------------===//
 
 #include "klee/Module/LocationInfo.h"
-#include "klee/Support/CompilerWarning.h"
+#include "klee/Module/SarifReport.h"
 
+#include "klee/Support/CompilerWarning.h"
 DISABLE_WARNING_PUSH
 DISABLE_WARNING_DEPRECATED_DECLARATIONS
 #include "llvm/ADT/SmallVector.h"
@@ -28,6 +29,28 @@ DISABLE_WARNING_POP
 
 namespace klee {
 
+PhysicalLocationJson LocationInfo::serialize() const {
+  // clang-format off
+  return PhysicalLocationJson{
+    {
+      ArtifactLocationJson {
+        {file}
+      }
+    },
+    {
+      RegionJson {
+        {line}, 
+        std::nullopt, 
+        column, 
+        std::nullopt
+      }
+    }
+  };
+  // clang-format on
+}
+
+////////////////////////////////////////////////////////////////
+
 LocationInfo getLocationInfo(const llvm::Function *func) {
   const auto dsub = func->getSubprogram();