libutil: Document hacks and problems around Pos class

This should provide context for follow-up commits in
the patch series.

Author: xokdvium

src/libutil/error.hh

@@ -50,6 +50,14 @@ struct LinesOfCode {
     std::optional<std::string> nextLineOfCode;
 };
 
+/* NOTE: position.hh recursively depends on source-path.hh -> source-accessor.hh
+   -> hash.hh -> config.hh -> experimental-features.hh -> error.hh -> Pos.
+   There are other such cycles.
+   Thus, Pos has to be an incomplete type in this header. But since ErrorInfo/Trace
+   have to refer to Pos, they have to use pointer indirection via std::shared_ptr
+   to break the recursive header dependency.
+   FIXME: Untangle this mess. Should there be AbstractPos as there used to be before
+   4feb7d9f71? */
 struct Pos;
 
 void printCodeLines(std::ostream & out,

src/libutil/pos-table.hh

@@ -76,6 +76,17 @@ public:
         return PosIdx(1 + origin.offset + offset);
     }
 
+    /**
+     * Convert a byte-offset PosIdx into a Pos with line/column information.
+     *
+     * @param p Byte offset into the virtual concatenation of all parsed contents
+     * @return Position
+     *
+     * @warning Very expensive to call, as this has to read the entire source
+     * into memory each time. Call this only if absolutely necessary. Prefer
+     * to keep PosIdx around instead of needlessly converting it into Pos by
+     * using this lookup method.
+     */
     Pos operator[](PosIdx p) const;
 
     Pos::Origin originOf(PosIdx p) const

src/libutil/position.hh

@@ -50,6 +50,7 @@ struct Pos
 
     explicit operator bool() const { return line > 0; }
 
+    /* TODO: Why std::shared_ptr<Pos> and not std::shared_ptr<const Pos>? */
     operator std::shared_ptr<Pos>() const;
 
     /**