Tidy comments; add docs helper

Author: dc-mak

cpp/src/reachability_analyzer.cpp

@@ -351,16 +351,12 @@ void ReachabilityAnalyzer::findMacroDefns(clang::PreprocessingRecord &pr,
 }
 
 // 1. The PreprocessingRecord only inlcudes the Macro expanded when typed into
-// the source,
-//    not any subsequent macros expanded _inside a macro_.
-// 2. None of
-// SourceManager::{getFileLoc,getExpansionLoc,get(Immediate)SpellingLoc}()
-// enable
-//    to go from the source _down_/expand the Macros, only to go from a fully
-//    expanded location back up to the source.
+//    the source, not any subsequent macros expanded _inside a macro_.
+// 2. None of getFileLoc, getExpansionLoc, get(Immediate)SpellingLoc, in
+//    SourceManager::() enable to go from the source _down_/expand the macros,
+//    only to go from a fully expanded location back up to the source.
 // 3. It seems difficult/not sensible to re-lex/pp the macro _definition_ to get
-// at the macros
-//    it refers to.
+//    at the macros it refers to.
 // Therefore, we add a PPCallback that records _all_ macro expansions, even
 // those that occur within a macro.
 void ReachabilityAnalyzer::ExecuteAction() {

cpp/src/reachability_analyzer.hpp

@@ -144,7 +144,7 @@ class PPRecordNested : public clang::PPCallbacks {
         // 2|//-"hi"
         // ```
         //
-        // Futhermore, it seems like the PreprocessingRecord is filled up first,
+        // Furthermore, it seems like the PreprocessingRecord is filled up first,
         // before any user-defined callbacks are run. This means that adjusting the
         // source range for macros in HandleMacroDefine is too late.
         if (const auto num_tokens = macro_info->getNumTokens(); num_tokens > 0) {

cpp/test/run_test.py

@@ -112,7 +112,6 @@ def __init__(self, carver):
             eprint("run './test/run_test.py make' first")
 
     def run(self, input_rel_path):
-        cwd = os.getcwd()
         completed = subprocess.run([self.carver, '-r=main', input_rel_path], capture_output=True, text=True)
         return completed.stdout if completed.stdout != None else completed.stderr
 

etc/docs.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+
+# This is a helper script to build and run LLVM docs locally with an indexed
+# search feature, which is invaluable for developing on a specific version.
+
+set -euo pipefail
+
+# export PS4="\$LINENO: "
+# set -xv
+
+mkdir -p build
+cd build
+addr=$(ip addr | grep eth0 | tail -n 1 | cut -d' ' -f6 | cut -d'/' -f1)
+[ -e Makefile ] || cmake \
+    -DLLVM_ENABLE_PROJECTS='clang' \
+    -DLLVM_ENABLE_DOXYGEN=ON \
+    -DLLVM_DOXYGEN_EXTERNAL_SEARCH=ON \
+    -DLLVM_DOXYGEN_SEARCHENGINE_URL="http://${addr}:8000/cgi-bin/doxysearch.cgi" \
+    -DDOXYGEN_EXECUTABLE="/usr/local/bin/doxygen" \
+    ../llvm
+[ -d tools/clang/docs/doxygen ] || make doxygen-clang
+cd tools/clang/docs/doxygen
+mkdir -p cgi-bin
+[ -e cgi-bin/doxysearch.cgi ] || cp $HOME/doxygen-1.9.4/bin/doxysearch.cgi cgi-bin
+[ -d doxysearch.db ] || $HOME/doxygen-1.9.4/bin/doxyindexer searchdata.xml
+# update URL incase it's changed
+sed -i "s~172.*:~${addr}:~g" html/search/search.js
+python3 -m http.server --cgi &
+echo "http://${addr}:8000/html"