libnixt: fix various doc-comments for doxygen (#287)

libnixt/include/nixt/Displacement.h

@@ -1,11 +1,22 @@
+/// \file
+/// \brief Get `nix::PosIdx` of an `nix::Expr`, from `nix::Displacement`.
+///
+/// "Displacement" is something used in variable lookup.
+
 #pragma once
 
 #include <nix/nixexpr.hh>
 
 namespace nixt {
 
+/// \brief Get `nix::PosIdx` of an `nix::Expr`, from `nix::Displacement`.
+/// \note This is based on dynamic_cast, so it is not very efficient.
+///
+/// The function actually invokes `displOf()` of the corresponding `Expr` type.
 nix::PosIdx displOf(const nix::Expr *E, nix::Displacement Displ);
 
+/// \note The function asserts `E->recursive`. Since normal `ExprAttrs` cannot
+/// do variable binding.
 nix::PosIdx displOf(const nix::ExprAttrs *E, nix::Displacement Displ);
 
 nix::PosIdx displOf(const nix::ExprLet *E, nix::Displacement Displ);

libnixt/include/nixt/Nodes.inc

@@ -1,7 +1,8 @@
-/// Nodes.inc, nix expressions declaration.
 /// \file
-/// This record file provides NIX_EXPR macro that contains all names of
-/// nix::Expr
+/// \brief Nix expressions declaration.
+///
+/// This record file provides `NIX_EXPR` macro that contains all names of
+/// `nix::Expr`
 
 #ifdef NIX_EXPR
 

libnixt/include/nixt/ParentMap.h

@@ -1,11 +1,16 @@
+/// \file
+/// \brief Construct child -> parent relations of `nix::Expr` nodes.
+
 #pragma once
 
 #include "Visitor.h"
 
 namespace nixt {
 
+/// \brief The parent map. The key is "child", the value is "parent".
 using ParentMap = std::map<const nix::Expr *, const nix::Expr *>;
 
+/// \brief Construct child -> parent relations of `nix::Expr` nodes.
 ParentMap parentMap(const nix::Expr *Root);
 
 } // namespace nixt

libnixt/include/nixt/Visitor.h

@@ -1,11 +1,50 @@
-/// Visitor.h, describe how to traverse upon nix::Expr * nodes.
+/// \file
+/// \brief Describe how to traverse upon nix::Expr * nodes.
+///
+/// This file contains a CRTP base class for traversing nix::Expr * nodes.
+
 #pragma once
 
 #include <nix/nixexpr.hh>
 #include <nix/symbol-table.hh>
 
+/// \brief Library for playing with `nix::Expr` nodes.
+///
+/// This is a library with some utilities playing with nix AST nodes (e.g.
+/// traversing, visiting, encoding, decoding, dispatching, printing). It is not
+/// a parser, so you should use other libraries to parse nix code.
+
 namespace nixt {
 
+/// \brief A
+/// [CRTP](https://en.wikipedia.org/wiki/Curiously_recurring_template_pattern)
+/// base class for traversing `nix::Expr *` nodes.
+///
+/// Usage:
+///
+/// \code{.cpp}
+/// struct MyVisitor : public RecursiveASTVisitor<MyVisitor> {
+///   // This can be omitted.
+///   bool traverseExpr(const nix::Expr *E) {
+///     // Do something before/after traversing children.
+///   }
+///
+///   // return `true` to traverse post-order, otherwise pre-order (default).
+///   bool shouldTraversePostOrder() { return true; }
+///
+///   // sreturn `true` if we should continue traversing.
+///   bool visitExprInt(const nix::ExprInt *E) { return true; }
+///   bool visitExprFloat(const nix::ExprFloat *E) { return true; }
+/// } V;
+/// V.traverseExpr(Root); // call traverseExpr() on Root.
+/// \endcode
+///
+/// \note This is based on dynamic_cast, so it is not very efficient.
+///
+/// `visit*()` methods are called once for each node.` traverse*()` methods are
+/// automatically generated describing relations between nodes. Usually you
+/// should always write custom `visit*()` methods, and only write `traverse*()`
+/// methods when you need to do something special.
 template <class Derived> struct RecursiveASTVisitor {
 
   bool shouldTraversePostOrder() { return false; }

libnixt/lib/ParentMap.cpp

@@ -5,7 +5,7 @@ namespace nixt {
 ParentMap parentMap(const nix::Expr *Root) {
   ParentMap Ret;
   struct VisitorClass : RecursiveASTVisitor<VisitorClass> {
-    /// The parent before traverseExpr
+    // The parent before traverseExpr
     const nix::Expr *ParentExpr;
     ParentMap *CapturedRet;