From 1c5fbd00a68e9a0aef8a3c695db6cfc1d0718bc9 Mon Sep 17 00:00:00 2001
From: Jukka Aho <ahojukka5@gmail.com>
Date: Sat, 9 May 2026 16:30:39 +0300
Subject: [PATCH] refactor(src): update api.jl

src/basis/api.jl | 43 ++++++++-----------------------------------  1 file changed, 8 insertions(+), 35 deletions(-)
---
 src/basis/api.jl | 43 ++++++++-----------------------------------
 1 file changed, 8 insertions(+), 35 deletions(-)

diff --git a/src/basis/api.jl b/src/basis/api.jl
index 37be460..f307f48 100644
--- a/src/basis/api.jl
+++ b/src/basis/api.jl
@@ -4,8 +4,7 @@
 using Tensors
 using LinearAlgebra
 
-# Re-export Vec for convenience (from Tensors.jl)
-export Vec
+# Vec is re-exported by `src/exports.jl` for convenience.
 
 """
     AbstractBasisDescription
@@ -125,7 +124,7 @@ end
 
 Return the number of basis functions for the given basis on the given topology.
 
-**Zero-cost:** This function compiles to a constant integer for concrete types.
+Zero-cost: This function compiles to a constant integer for concrete types.
 The return value is compile-time known, enabling type-stable allocations and
 constant propagation throughout assembly code.
 
@@ -143,9 +142,6 @@ nbasis(Triangle{3}(), Lagrange{1}())       # 3 (linear triangle)
 nbasis(Triangle{6}(), Lagrange{2}())       # 6 (quadratic triangle)
 nbasis(Tetrahedron{10}(), Lagrange{2}())   # 10 (quadratic tetrahedron)
 
-# Exotic elements (nodes ≠ basis functions)
-nbasis(Triangle{3}(), DKT())               # 9 (3 nodes but 9 DOFs!)
-
 # Serendipity families
 nbasis(Quadrilateral{8}(), Serendipity{2}())  # 8 (reduced quadratic quad)
 ```
@@ -157,10 +153,9 @@ generated by `basis_generator.jl` alongside the basis function implementations.
 This ensures consistency: the generator knows exactly how many basis functions
 it produced, so `nbasis` always returns the correct value.
 
-For custom/special bases (DKT, hierarchical, etc.), implement manually:
-```julia
-@inline nbasis(::Triangle{3}, ::DKT) = 9
-```
+For specialised bases that fall outside the Vandermonde catalogue (e.g.
+hierarchical refinement, plate-bending shape functions), implement
+`nbasis` manually next to the basis definition.
 
 For truly dynamic bases (adaptive refinement), use instance-based dispatch:
 ```julia
@@ -189,31 +184,9 @@ function validate_dof_consistency(dof, K, P)
 end
 ```
 
-See also: [`get_basis_functions`](@ref), [`validate_dof_consistency`](@ref)
+See also: [`get_basis_functions`](@ref). The `validate_dof_consistency` sketch
+above is illustrative; it is not a separate exported API entry point.
 """
 function nbasis end
 
-# ---------------------------------------------------------------------------
-# Deprecated bridge (old API names)
-# ---------------------------------------------------------------------------
-
-"""
-    eval_basis!(basis_type, xi) (DEPRECATED)
-
-Use `get_basis_functions(topology, basis, xi)` instead.
-Provided temporarily for migration.
-"""
-function eval_basis! end
-
-"""
-    eval_dbasis!(basis_type, xi) (DEPRECATED)
-
-Use `get_basis_derivatives(topology, basis, xi)` instead.
-Provided temporarily for migration.
-"""
-function eval_dbasis! end
-
-export AbstractBasis, Lagrange, Serendipity
-export get_basis_functions, get_basis_derivatives, get_basis_function, get_basis_derivative
-export nbasis
-export eval_basis!, eval_dbasis!
+# Exports for these types live in `src/exports.jl`.