[refactor, WIP] Added more docs for code.

Author: S1eGa

lib/Core/CodeEvent.h

@@ -52,4 +52,4 @@ class CodeEvent {
 
 } // namespace klee
 
-#endif
+#endif // KLEE_CODE_EVENT_H

lib/Core/CodeEvents/AllocEvent.h

@@ -40,4 +40,4 @@ struct AllocEvent : public CodeEvent {
 
 } // namespace klee
 
-#endif
+#endif // KLEE_ALLOC_EVENT_H

lib/Core/CodeEvents/BrEvent.h

@@ -10,6 +10,8 @@ namespace klee {
 
 class BrEvent : public CodeEvent {
 private:
+  /// @brief Described chosen branch event: `true` if
+  /// `then`-branch was chosen and `false` otherwise.
   bool chosenBranch = true;
 
 public:
@@ -40,4 +42,4 @@ class BrEvent : public CodeEvent {
 
 } // namespace klee
 
-#endif
+#endif // KLEE_BR_EVENT_H

lib/Core/CodeEvents/CallEvent.h

@@ -35,4 +35,4 @@ class CallEvent : public CodeEvent {
 
 } // namespace klee
 
-#endif
+#endif // KLEE_CALL_EVENT_H

lib/Core/CodeEvents/ErrorEvent.h

@@ -11,9 +11,15 @@ namespace klee {
 
 struct ErrorEvent : public CodeEvent {
 public:
+  /// @brief ID for this error.
   const StateTerminationType ruleID;
+
+  /// @brief Message describing this error.
   const std::string message;
 
+  /// @brief Event associated with this error
+  /// which may be treated as a "source" of error
+  /// (e.g. memory allocation for Out-Of-Bounds error).
   const std::optional<ref<CodeEvent>> source;
 
   ErrorEvent(const ref<CodeEvent> &source, const ref<CodeLocation> &sink,
@@ -35,4 +41,4 @@ struct ErrorEvent : public CodeEvent {
 
 } // namespace klee
 
-#endif
+#endif // KLEE_ERROR_EVENT_H

lib/Core/CodeEvents/ReturnEvent.h

@@ -11,6 +11,7 @@ namespace klee {
 
 class ReturnEvent : public CodeEvent {
 private:
+  /// @brief Function to which control flow returns.
   const KFunction *const caller;
 
 public:
@@ -30,4 +31,4 @@ class ReturnEvent : public CodeEvent {
 
 } // namespace klee
 
-#endif
+#endif // KLEE_RETURN_EVENT_H

lib/Core/CodeLocation.h

@@ -73,4 +73,4 @@ struct CodeLocation {
 
 }; // namespace klee
 
-#endif
+#endif // KLEE_CODE_LOCATION_H

lib/Core/EventRecorder.cpp

@@ -7,6 +7,7 @@
 #include "klee/Module/SarifReport.h"
 
 #include <cassert>
+#include <optional>
 #include <utility>
 
 using namespace klee;
@@ -59,12 +60,12 @@ EventRecorder EventRecorder::inRange(const Path::PathIndex &begin,
     return result;
   }
 
-  // TODO: not effective.
-  /// FIXME:
   for (const auto &event : events) {
     const Path::PathIndex &eventPathIndex = event->location->pathIndex;
-    if (!Path::PathIndexCompare{}(eventPathIndex, begin) &&
-        !Path::PathIndexCompare{}(end, eventPathIndex)) {
+    if (!Path::PathIndexCompare{}(eventPathIndex, begin)) {
+      if (Path::PathIndexCompare{}(end, eventPathIndex)) {
+        break;
+      }
       result.record(event);
     }
   }

lib/Core/EventRecorder.h

@@ -25,7 +25,7 @@ class EventRecorder {
   ~EventRecorder() = default;
 
   /// @brief Remembers event.
-  /// @param event event to record.
+  /// @param event Event to record.
   void record(const ref<CodeEvent> &event);
 
   /// @brief Appends all events from the given `EventRecorder`

lib/Module/Passes.h

@@ -221,15 +221,38 @@ class ReturnSplitter : public llvm::FunctionPass {
   bool runOnFunction(llvm::Function &F) override;
 };
 
-/// @brief
-/// FIXME: finish docs.
+/// @brief Pass able to find the actual location of
+/// `return` statements in source code.
+///
+/// @details For function with multiple `return` statements
+/// clang compiler generates LLVM IR with exactly one `ret`
+/// instruction. `return` statements transform to the:
+///   ```
+///     ret_reg = val
+///     br ret_block
+///   ...
+///   ret_block:
+///     ret_val = load ret_reg
+///     ret ret_val
+///   ```
+/// This pass finds such constructions and marks
+/// `br ret_block` with `md_ret` metadata.
 class ReturnLocationFinderPass : public llvm::FunctionPass {
 public:
   static char ID;
   ReturnLocationFinderPass() : llvm::FunctionPass(ID) {}
   bool runOnFunction(llvm::Function &) override;
 };
 
+/// @brief Pass able to find line in source code with
+/// declaration of local variable.
+///
+/// @details "Construction" of local variable in LLVM IR
+/// is represented as allocation of memory in the beginning
+/// of each function and subsequent call of `llvm.dbg.declare`
+/// function on allocated memory. This pass moves `!dbg` infos
+/// from calls to mentioned functions to the corresponding `alloca`
+/// instructions.
 class LocalVarDeclarationFinderPass : public llvm::FunctionPass {
 public:
   static char ID;