improve some index notation doc strings

Author: Jutho

src/indexnotation/contractiontrees.jl

@@ -2,10 +2,17 @@
     processcontractions(ex, treebuilder, treesorter, costcheck)
 
 Process the contractions in `ex` using the given `treebuilder` and `treesorter` functions.
-This is done by first extracting a network representation from the expression, then
-building and sorting the contraction trees with a given `treebuilder` and `treesorter`
-function, and finally inserting the contraction trees back into the expression. When the 
-`costcheck` function is provided, the cost of each contraction is computed and comp
+This is done by first extracting a network representation from the expression, then building
+and sorting the contraction trees with a given `treebuilder` and `treesorter` function, and
+finally inserting the contraction trees back into the expression. When the `costcheck`
+argument equals `:warn` or `:cache` (as opposed to `:nothing`), the optimal contraction
+order is computed at runtime using the actual values of [`tensorcost`](@ref) and this
+optimal order is compared to the contraction order that was determined at compile time. If
+the compile time order deviated from the optimal order, a warning will be printed (in case
+of `costcheck == :warn`) or this particular contraction will be recorded in
+`TensorOperations.costcache` (in case of `costcheck == :cache`). Both the warning or the 
+recorded cache entry contain a `order` suggestion that can be passed to the `@tensor` macro
+in order to encode the optimal contraction order at compile time..
 """
 function processcontractions(ex, treebuilder, treesorter, costcheck)
     if isexpr(ex, :block)

src/indexnotation/parser.jl

@@ -43,10 +43,12 @@ end
     verifytensorexpr(ex)
 
 Check that `ex` is a valid tensor expression and throw an `ArgumentError` if not.
-Valid tensor expressions are characterized by one of the following properties:
+Valid tensor expressions satisfy one of the following (recursive) rules):
 - The expression is a scalar expression or a tensor expression.
 - The expression is an assignment or a definition, and the left hand side and right hand side are valid tensor expressions or scalars.
 - The expression is a block, and all subexpressions are valid tensor expressions or scalars.
+
+See also [`istensorexpr`](@ref) and [`isscalarexpr`](@ref).
 """
 function verifytensorexpr(ex)
     if isexpr(ex, :block)
@@ -73,7 +75,8 @@ end
 """
     tensorify(ex)
 
-Parse `ex` into a series of tensor operations' building blocks.
+Main parsing step to transform a tensor expression `ex` into a series of function calls associated
+with the primitive building blocks (tensor operations and allocations).
 """
 function tensorify(ex::Expr)
     if isexpr(ex, :macrocall) && ex.args[1] == Symbol("@notensor")

src/indexnotation/postprocessors.jl

@@ -1,7 +1,7 @@
 """
     _flatten(ex)
 
-Flatten nested structure of an expression, returning a flat line of expressions.
+Flatten nested structure of an expression, returning an unnested `Expr(:block, …)`.
 """
 function _flatten(ex)
     if isa(ex, Expr) # prewalk