some documentation fixes (#42)

supported by github copilot

Author: chmerdon

docs/src/interpolations.md

@@ -13,10 +13,13 @@ The qpinfo argument communicates vast information of the current quadrature poin
 | qpinfo.x           | Vector{Real}       | space coordinates of quadrature point |
 | qpinfo.time        | Real               | current time |
 | qpinfo.item        | Integer            | current item that contains qpinfo.x |
+| qpinfo.cell        | Integer            | cell number (when reasonable) |
 | qpinfo.region      | Integer            | region number of item |
 | qpinfo.xref        | Vector{Real}       | reference coordinates within item of qpinfo.x |
 | qpinfo.volume      | Real               | volume of item |
+| qpinfo.normal      | Vector{Real}       | normal vector (when reasonable) |
 | qpinfo.params      | Vector{Any}        | parameters that can be transferred via keyword arguments |
+| qpinfo.grid        | ExtendableGrid     | full access to grid |
 
 
 ## Standard Interpolations

examples/Example205_LowLevelSpaceTimePoisson.jl

@@ -1,6 +1,6 @@
 #=
 
-# 205 : Space-Time FEM for Poisson Problem
+# 205 : Space-Time FEM for Heat Equation
 ([source code](@__SOURCE_URL__))
 
 This example computes the solution ``u`` of the

examples/Example210_LowLevelNavierStokes.jl

@@ -3,21 +3,21 @@
 # 210 : Navier-Stokes Problem
 ([source code](@__SOURCE_URL__))
 
-Consider the Navier-Stokes problem that seeks ``u`` and ``p`` such that
+Consider the Navier-Stokes problem that seeks ``\mathbf{u}`` and ``p`` such that
 ```math
 \begin{aligned}
-	- \mu \Delta u + (u \cdot \nabla) u + \nabla p &= f\\
-			\mathrm{div}(u) & = 0.
+    - \mu \Delta \mathbf{u} + (\mathbf{u} \cdot \nabla) \mathbf{u} + \nabla p &= \mathbf{f} \\
+    \mathrm{div}(\mathbf{u}) & = 0.
 \end{aligned}
 ```
 
-The weak formulation seeks ``u \in V := H^1_0(\Omega)`` and ``p \in Q := L^2_0(\Omega)`` such that
+The weak formulation seeks ``\mathbf{u} \in V := H^1_0(\Omega)^2`` and ``p \in Q := L^2_0(\Omega)`` such that
 ```math
 \begin{aligned}
-	\mu (\nabla u, \nabla v) + ((u \cdot \nabla) u, v) - (p, \mathrm{div}(v)) & = (f, v)
-	& \text{for all } v \in V\\
-	(q, \mathrm{div}(u)) & = 0
-	& \text{for all } q \in Q\\
+    \mu (\nabla \mathbf{u}, \nabla \mathbf{v}) + ((\mathbf{u} \cdot \nabla) \mathbf{u}, \mathbf{v}) - (p, \mathrm{div}(\mathbf{v})) & = (\mathbf{f}, \mathbf{v})
+    & \text{for all } \mathbf{v} \in V\\
+    (q, \mathrm{div}(\mathbf{u})) & = 0
+    & \text{for all } q \in Q\\
 \end{aligned}
 ```
 This example computes a planar lattice flow with inhomogeneous Dirichlet boundary conditions

src/feevaluator.jl

@@ -58,8 +58,6 @@ A `FEEvaluator` object that can efficiently evaluate (and cache) the values of t
 # Notes
 
 - For matrix-valued operators (e.g., `Gradient`), the result is stored as a long vector in component-wise order.
-- The evaluator is designed for high performance in assembly loops and supports both scalar and vector-valued elements and operators.
-- For advanced use, the evaluator exposes internal fields for basis values, derivatives, and transformation matrices.
 
 # Example
 
@@ -69,6 +67,7 @@ for cell in 1:ncells
     update_basis!(FEB, cell)
     # Access FEB.cvals for basis gradients at quadrature points
 end
+```
 """
 function FEEvaluator(
         FE::FESpace{TvG, TiG, FEType, FEAPT},

src/point_evaluator.jl

@@ -22,33 +22,34 @@ default_peval_kwargs() = Dict{Symbol, Tuple{Any, String}}(
 
 
 """
-````
-function Pointevaluator(
-	[kernel!::Function],
-	oa_args::Array{<:Tuple{<:Any, DataType},1}
-    sol = nothing;
-	kwargs...)
-````
+$(TYPEDSIGNATURES)
 
-Constructs a `PointEvaluator` object for evaluating operator expressions at arbitrary points in a finite element space.
+Construct a `PointEvaluator` object for evaluating operator expressions at arbitrary points in a finite element space.
 
-A `PointEvaluator` can be used to evaluate one or more operator evaluations (e.g., function values, gradients) at arbitrary points, optionally postprocessed by a user-supplied kernel function. The evaluation is performed with respect to a given solution and finite element basis.
-
-If a kernel function is provided, it must have the interface:
-    kernel!(result, eval_args, qpinfo)
-where `result` is the output buffer, `eval_args` contains the operator evaluations, and `qpinfo` provides information about the current evaluation point.
-
-Operator evaluations are specified as tuples pairing a tag (to identify the unknown or vector position) with a `FunctionOperator`.
+A `PointEvaluator` can be used to evaluate one or more operator evaluations (e.g., function values, gradients) at arbitrary points, optionally postprocessed by a user-supplied kernel function. The evaluation is performed with respect to a given solution and its finite element basis.
 
 After construction, the `PointEvaluator` must be initialized with a solution using `initialize!`. Evaluation at a point is then performed using `evaluate!` or `evaluate_bary!`.
 
 # Arguments
-- `kernel!` (optional): Postprocessing function for operator evaluations.
-- `oa_args: Array of operator argument tuples (source block tag, operator type).
+- `kernel!` (optional): Postprocessing function for operator evaluations. Should have the form `kernel!(result, eval_args, qpinfo)`.
+- `oa_args`: Array of operator argument tuples `(source block tag, operator type)`.
 - `sol` (optional): Solution object for immediate initialization.
 
 # Keyword arguments:
 $(_myprint(default_peval_kwargs()))
+
+# Kernel Function Interface
+
+    kernel!(result, eval_args, qpinfo)
+
+- `result`: Preallocated array to store the kernel output.
+- `eval_args`: Array of operator evaluations at the current evaluation point.
+- `qpinfo`: `QPInfos` struct with information about the current evaluation point.
+
+# Usage
+
+After construction, call `initialize!` to prepare the evaluator for a given solution, then use `evaluate!` or `evaluate_bary!` to perform point evaluations.
+
 """
 function PointEvaluator(kernel, u_args, ops_args, sol = nothing; Tv = Float64, kwargs...)
     parameters = Dict{Symbol, Any}(k => v[1] for (k, v) in default_peval_kwargs())
@@ -93,6 +94,20 @@ This function prepares the `PointEvaluator` for evaluation by associating it wit
 - `time`: (default: `0`) Time value to be passed to the quadrature point info structure.
 $(_myprint(default_peval_kwargs()))
 
+# Notes
+- This function must be called before using `evaluate!` or `evaluate_bary!` with the `PointEvaluator`.
+Initializes the given `PointEvaluator` for a specified solution (FEVector or vector of FEVectorBlocks).
+
+This function prepares the `PointEvaluator` for evaluation by associating it with the provided solution vector. It sets up the necessary finite element basis evaluators, local-to-global transformations, and cell finder structures for the underlying grid.
+
+# Arguments
+- `O::PointEvaluator`: The `PointEvaluator` instance to initialize.
+- `sol`: The solution object (e.g., array of FEVectorBlocks) to be used for evaluations.
+
+# Keyword Arguments
+- `time`: (default: `0`) Time value to be passed to the quadrature point info structure.
+$(_myprint(default_peval_kwargs()))
+
 # Notes
 - This function must be called before using `evaluate!` or `evaluate_bary!` with the `PointEvaluator`.
 """