Merge pull request #99 from WIAS-PDELib/doc/tdict

Add `TDict` doc entry and add a small summary

Author: pjaap

docs/Project.toml

@@ -16,7 +16,6 @@ Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 Triangulate = "f7e6ffb2-c36d-4f8f-a77e-16e897189344"
 
 [compat]
-CairoMakie = "0.12"
 Documenter = "1"
 ExampleJuggler = "2"
 julia = "1.9"

docs/make.jl

@@ -38,6 +38,7 @@ function mkdocs()
             "adjacency.md",
             "vectorofconstants.md",
             "typehierarchy.md",
+            "tdict.md",
             "elementgeometry.md",
             "shape_specs.md",
             "coordinatesystem.md",

docs/src/tdict.md

@@ -3,7 +3,18 @@
 Here we describe the idea behind the data structure used in this package.
 TDict means: extendable containers with type stable content access and lazy content creation via the Julia type system.
 
-### Problem to be addressed
+### TL;DR: We access grid components using types as keys.
+
+- e.g., coordinates: `grid[Coordinates]` by type `Coordinates`
+- we implement a custom method for `Base.getindex` with __explicit return type__ (!) for any key type
+- non-existent dictionary entries are created lazily by an `instantiate` method
+- how to add a new grid component with key type `T` and value type `TV`?
+  - make `T <: AbstractGridComponent`
+  - add a method `Base.getindex(grid::ExtendableGrid{Tc, Ti}, ::Type{T})::TV where {Tc, Ti} = get!(grid, T)` for type stability (note the `TV`!)
+  - optional: add a method `instantiate(grid, ::Type{T})` to generate component `T` from other grid components
+
+
+## Problem to be addressed
 
 In certain contexts it is desirable to use containers with core components
 which are user extendable and allow for type stable component access. Moreover,
@@ -13,14 +24,14 @@ from typos in component names etc.
 
 Julia default data structures do not provide these properties.
 
-#### `struct` 
+### `struct`
   - Julia structs with proper field type annotations guarantee type stability
   - Julia structs are not extendable, fields and their types are fixed upon definition
   - If we don't fix types of struct fields they become Any and a source 
     for type instability
   - The situation could be fixed if `getfield` could be overloaded but it can't
 
-#### `Dict`
+### `Dict`
   - Plain Dicts with flexible value types are a source of type instability
   - Dicts with strings as keys needs a meta protocol to handle
     semantics of keys which at the end probably hinges on string comparison which
@@ -29,7 +40,7 @@ Julia default data structures do not provide these properties.
   - Same for the implementation of a lazy evaluation protocol
   - If a dict contains components of different types, component access will not be typestable
 
-### Proposed solution:
+## Proposed solution:
 
 Harness the power of the Julia type system: 
 - Use a struct containing a  Dict with DataType as keys. Every key is a type.
@@ -41,9 +52,9 @@ Harness the power of the Julia type system:
 - Component access is made type stable by type dispatched`getindex` methods
 - Component insertion is made safe by having  `setindex!`  calling a `veryform` method
 
-#### Pros
+### Pros
 See above ...
 
-#### Cons
+### Cons
 - Implemented using a Dict, so access is inherently slower than access to a component
   of a struct. Therefore it is not well suited for inner loops.