libutil: Document hacks and problems around Pos class

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

(cherry picked from commit bf12aedf2e)

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