Update docs

Author: hughcars

docs/src/solidmodels.md

@@ -68,10 +68,47 @@ Other operations:
 
 ### Meshing
 
-Entities can carry mesh sizing information with them when rendered to a `SolidModel`. Many entities will default to a maximal size to reasonably resolve the geometry. This is particularly useful together with adaptive mesh refinement to efficiently refine your mesh to minimize estimated error with as few elements as possible. You can also style entities with [`MeshSized`](@ref) to manually control mesh sizing, and provide `MeshingParameters` to `render!` using the `meshing_parameters` keyword argument.
+Entities can carry mesh sizing information with them when rendered to a `SolidModel`. Many
+entities will default to a maximal size to reasonably resolve the geometry. This is
+particularly useful together with adaptive mesh refinement to efficiently refine your mesh
+to minimize estimated error with as few elements as possible. You can also style entities
+with [`MeshSized`](@ref) to manually control mesh sizing, the [`SolidModels.mesh_scale`](@ref),
+[`SolidModels.mesh_order`](@ref) and [`SolidModels.mesh_grading_default`](@ref) methods are used to modify the
+global default parameters used in each sizing field (see [`MeshSized`](@ref)).
+
+Size fields within a `SolidModel` are specified in terms of control points, which are
+spatial locations combined with an `(h, α)` as in [`MeshSized`](@ref). When a model is
+rendered, a set of control points are computed from the geometry, and these are then used to
+create `KDTree` structures to allow for rapid evaluation. Additional points can be manually
+inserted into a `SolidModel` after `render!` is called, and the global size parameters
+[`SolidModels.mesh_scale`](@ref), [`SolidModels.mesh_order`](@ref) and [`SolidModels.mesh_grading_default`](@ref) modified without requiring `render!`
+to be called again. This allows for iteration on the mesh for a given fixed geometry. Manual
+modification of the control points is in general not necessary but can be achieved through
+[`DeviceLayout.SolidModels.add_mesh_size_point`](@ref), [`DeviceLayout.SolidModels.finalize_size_fields!`](@ref),
+[`DeviceLayout.SolidModels.clear_mesh_control_points!`](@ref) and
+[`DeviceLayout.SolidModels.reset_mesh_control!`](@ref).
+
+!!! info
+
+    If [`SolidModels.mesh_control_points`](@ref) is modified, then it is important to call
+    [`SolidModels.finalize_size_fields!`](@ref) in order to ensure that the `KDTree` are rebuilt.
+    Additionally, to generate a new mesh `SolidModels.gmsh.model.mesh.clear()` must be called
+    otherwise `gmsh` will return only any previously generated mesh.
 
 ```@docs
     SolidModels.MeshingParameters
+    SolidModels.mesh_order
+    SolidModels.mesh_scale
+    SolidModels.mesh_grading_default
+    SolidModels.set_gmsh_option
+    SolidModels.get_gmsh_number
+    SolidModels.get_gmsh_string
+    SolidModels.mesh_control_points
+    SolidModels.mesh_control_trees
+    SolidModels.add_mesh_size_point
+    SolidModels.finalize_size_fields!
+    SolidModels.clear_mesh_control_points!
+    SolidModels.reset_mesh_control!
 ```
 
 ## Example

src/solidmodels/render.jl

@@ -611,7 +611,7 @@ Returns a `Dict{Tuple{Float64, Float64}, Vector{SVector{3, Float64}}}` where key
 `(mesh_size, grading_parameter)` tuples and values are vectors of 3D points.
 
 If this dictionary is modified, by erasing points or adding points using
-[`add_mesh_size_point`](@ref), then it is necessary to call [`finalize_size_fields`](@ref)
+[`add_mesh_size_point`](@ref), then it is necessary to call [`finalize_size_fields!`](@ref)
 to rebuild the KDTree from the data, else any resulting mesh will not reflect the change in
 data.
 """
@@ -660,10 +660,11 @@ end
         options::Dict{String, Float64} = Dict{String, Float64}()
     end
 
+α
+
 !!! warning "Deprecated"
 
-    This struct is deprecated. Use [`mesh_scale`](@ref), [`mesh_grading_default`](@ref),
-    [`mesh_order`](@ref), and [`gmsh_option`](@ref) instead.
+    This struct is deprecated. See [`render!`](@ref)
 
 MeshingParameters contains high level parameters to specify mesh sizing
 fields throughout the domain.
@@ -734,14 +735,14 @@ Render `cs` to `sm`.
     Map all metadata to zero.
   - `gmsh_options`: Dictionary of gmsh option name-value pairs to set before meshing.
   - `meshing_parameters`: **Deprecated.** Use individual mesh control functions
-    [`mesh_scale`](@ref), [`mesh_order`](@ref) and [`mesh_grading_default`](@ref), along with
+    [`DeviceLayout.SolidModels.mesh_scale`](@ref), [`DeviceLayout.SolidModels.mesh_order`](@ref) and [`DeviceLayout.SolidModels.mesh_grading_default`](@ref), along with
     `gmsh_options` instead.
 
 Available postrendering operations include [`translate!`](@ref), [`extrude_z!`](@ref), [`revolve!`](@ref),
 [`union_geom!`](@ref), [`intersect_geom!`](@ref), [`difference_geom!`](@ref), [`fragment_geom!`](@ref), and [`box_selection`](@ref).
 (The geometric Boolean operations are only available for models using the OpenCASCADE kernel.)
 
-Additional keyword arguments are passed to [`SolidModels.to_primitives`](@ref) (which falls back to
+Additional keyword arguments are passed to [`DeviceLayout.SolidModels.to_primitives`](@ref) (which falls back to
 [`to_polygons`](@ref)) and may be used for
 certain entity types to control how entities of `cs` are converted to primitives and added to `sm`.
 """

src/styles.jl

@@ -158,11 +158,11 @@ mesh size = h * max(s_g, (d/h)^α)
 ```
 
 where d is the distance away from the styled entity, and `s_g` is the global mesh scale
-parameter specified in [`SolidModels.mesh_scale`](@ref). A smaller value of `h` will give a finer mesh
+parameter specified in [`DeviceLayout.SolidModels.mesh_scale`](@ref). A smaller value of `h` will give a finer mesh
 attached to the styled entity, and a larger value of `α` will give a more rapid increase in
 size away from the styled entity.
 
-If `α < 0`, the size field will use [`SolidModels.mesh_grading_default`](@ref) used in rendering.
+If `α < 0`, the size field will use [`DeviceLayout.SolidModels.mesh_grading_default`](@ref) used in rendering.
 
 See also [`meshsized_entity`](@ref).
 """
@@ -183,11 +183,11 @@ mesh size = h * max(s_g, (d/h)^α)
 ```
 
 where d is the distance away from the styled entity, and `s_g` is the global mesh scale
-parameter specified in [`SolidModels.mesh_scale`](@ref). A smaller value of `h` will give a finer mesh
+parameter specified in [`DeviceLayout.SolidModels.mesh_scale`](@ref). A smaller value of `h` will give a finer mesh
 attached to the styled entity, and a larger value of `α` will give a more rapid increase in
 size away from the styled entity.
 
-If `α < 0`, the size field will use [`SolidModels.mesh_grading_default`](@ref) used in rendering.
+If `α < 0`, the size field will use [`DeviceLayout.SolidModels.mesh_grading_default`](@ref) used in rendering.
 """
 meshsized_entity(ent::GeometryEntity, h::T, α::S=-1.0) where {T, S <: Real} =
     MeshSized(h, α)(ent)