some notes in docstrings (#171)

NEWS.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## v1.1.2
+
+- Clarified type stability of `triangulate` in docstring, and notes about field access and public API. See [#171](https://github.com/JuliaGeometry/DelaunayTriangulation.jl/pull/171).
+
+## v1.1.1
+
+- Fixed issue on nightly with symbolics being marked as both public and exported. See [#168](https://github.com/JuliaGeometry/DelaunayTriangulation.jl/pull/168).
+
 ## v.1.1.0
 
 There are a lot of changes in this release, most of them irrelevant for the user. The most important change is the following:

Project.toml

@@ -1,7 +1,7 @@
 name = "DelaunayTriangulation"
 uuid = "927a84f5-c5f4-47a5-9785-b46e178433df"
 authors = ["Daniel VandenHeuvel <danj.vandenheuvel@gmail.com>"]
-version = "1.1.1"
+version = "1.1.2"
 
 [deps]
 AdaptivePredicates = "35492f91-a3bd-45ad-95db-fcad7dcfedb7"

docs/src/api/overview.md

@@ -17,6 +17,9 @@ This section provides docstrings for all functions in the public API, split into
 
 We emphasise that a function having a docstring does **NOT** guarantee it being in the public API - only it being listed here will guarantee this.
 
+We also note that, for more structs such as `Triangulation` and `VoronoiTessellations`, their fields are not intended to be in the public API. Rather, their 
+associated accessor functions are intended to be used, e.g. prefer `get_X(tri)` instead of `tri.X` for `tri::Triangulation`.
+
 Each section will first start with the list of all functions to be listed, and then the docstrings of those functions will be given. There will be some docstrings that fit into multiple categories, in which case one is chosen. Here is an index of all the functions listed in the above pages.
 
 ```@index 

src/algorithms/triangulation/main.jl

@@ -54,6 +54,12 @@ For the keyword arguments below, you may like to review the extended help as som
 # Outputs
 - `tri::Triangulation`: The triangulation.
 
+!!! note "Type stability"
+
+    The output from this function is currently not type stable. In particular, the inferred type is only `Triangulation` without any other information.
+    If you are depending on the output from `triangulate` inside some other function, you should consider putting the output behind a function barrier;
+    information about using function barriers is given [here](https://docs.julialang.org/en/v1/manual/performance-tips/#kernel-functions).
+
 # Extended help
 
 Here are some warnings to consider for some of the arguments.

src/data_structures/triangulation/triangulation.jl

@@ -3,6 +3,13 @@
 
 Struct representing a triangulation, as constructed by [`triangulate`](@ref).
 
+!!! note "Field access"
+
+    Accessing the fields themselves using e.g. `tri.field` is not recommended and is not intended 
+    to be in the public API. You should be using the 
+    accessor functions, e.g. instead of `tri.points` do `get_points(tri)`. Similarly, for the iterators,
+    e.g. `tri.triangles`, `each_triangle(tri)` is recommended instead.
+
 # Fields 
 - `points::P`
 
@@ -12,7 +19,7 @@ each vertex in the triangulation.
 - `triangles::T`
 
 The triangles in the triangulation. Each triangle is oriented counter-clockwise. If your triangulation has ghost triangles,
-some of these triangles will contain ghost vertices (i.e., vertices negative indices). Solid triangles can be iterated over using 
+some of these triangles will contain ghost vertices (i.e., vertices with negative indices). Solid triangles can be iterated over using 
 [`each_solid_triangle`](@ref).
 - `boundary_nodes::BN`
 
@@ -28,7 +35,8 @@ This is similar to `segments`, except this includes both the interior segments a
 - `weights::W`
 
 The weights of the triangulation. If you are not using a weighted triangulation, this will be given by `ZeroWeight()`. Otherwise, 
-the weights must be such that `get_weight(weights, i)` is the weight for the `i`th vertex. The weights should be `Float64`.
+the weights must be such that `get_weight(weights, i)` is the weight for the `i`th vertex. The weights should have the same type as the 
+coordinates in `points`.
 - `adjacent::Adjacent{I,E}`
 
 The [`Adjacent`](@ref) map of the triangulation. This maps edges `(u, v)` to vertices `w` such that `(u, v, w)` is a positively 

src/data_structures/voronoi.jl

@@ -5,6 +5,13 @@ Struct for representing a Voronoi tessellation.
 
 See also [`voronoi`](@ref).
 
+!!! note "Field access"
+
+    Accessing the fields themselves using e.g. `vorn.field` is not recommended and is not intended 
+    to be in the public API. You should be using the 
+    accessor functions, e.g. instead of `vorn.adjacent` do `get_adjacent(vorn)`. Similarly, for the iterators,
+    e.g. `vorn.generators`, `each_generators(vorn)` is recommended instead.
+
 # Fields 
 - `triangulation::Tr`: The underlying triangulation. The tessellation is dual to this triangulation, 
    although if the underlying triangulation is constrained then this is no longer the case (but it is