Document Plane and geometry filter APIs

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 - Remove the deprecated `SimplexNoise` class.
 - Optimized the `identity` constructors on the `Matrix` classes.
+- Documented the public `Plane` and geometry filter APIs.
 
 ## 2.3.0
 

lib/src/vector_math/plane.dart

@@ -4,8 +4,11 @@
 
 part of '../../vector_math.dart';
 
+/// Defines a plane with a [normal] vector and a [constant].
 class Plane {
   final Vector3 _normal;
+
+  /// The constant term in the plane equation.
   double constant;
 
   /// Find the intersection point between the three planes [a], [b] and [c] and
@@ -33,35 +36,44 @@ class Plane {
       ..z = (v1.z + v2.z + v3.z) / f;
   }
 
+  /// The normal vector of this plane.
   Vector3 get normal => _normal;
 
+  /// Create a plane with a zero [normal] and zero [constant].
   Plane() : _normal = Vector3.zero(), constant = 0.0;
 
+  /// Create a plane as a copy of [other].
   Plane.copy(Plane other)
     : _normal = Vector3.copy(other._normal),
       constant = other.constant;
 
+  /// Create a plane from normal components and a [constant].
   Plane.components(double x, double y, double z, this.constant)
     : _normal = Vector3(x, y, z);
 
+  /// Create a plane from a normal vector and a [constant].
   Plane.normalconstant(Vector3 normal_, this.constant)
     : _normal = Vector3.copy(normal_);
 
+  /// Copy the [normal] and [constant] from [o] into this.
   void copyFrom(Plane o) {
     _normal.setFrom(o._normal);
     constant = o.constant;
   }
 
+  /// Set the normal components and constant term of this plane.
   void setFromComponents(double x, double y, double z, double w) {
     _normal.setValues(x, y, z);
     constant = w;
   }
 
+  /// Normalize this plane so that [normal] has unit length.
   void normalize() {
     final inverseLength = 1.0 / normal.length;
     _normal.scale(inverseLength);
     constant *= inverseLength;
   }
 
+  /// Return the signed distance from [point] to this plane.
   double distanceToVector3(Vector3 point) => _normal.dot(point) + constant;
 }

lib/src/vector_math_64/plane.dart

@@ -4,8 +4,11 @@
 
 part of '../../vector_math_64.dart';
 
+/// Defines a plane with a [normal] vector and a [constant].
 class Plane {
   final Vector3 _normal;
+
+  /// The constant term in the plane equation.
   double constant;
 
   /// Find the intersection point between the three planes [a], [b] and [c] and
@@ -33,35 +36,44 @@ class Plane {
       ..z = (v1.z + v2.z + v3.z) / f;
   }
 
+  /// The normal vector of this plane.
   Vector3 get normal => _normal;
 
+  /// Create a plane with a zero [normal] and zero [constant].
   Plane() : _normal = Vector3.zero(), constant = 0.0;
 
+  /// Create a plane as a copy of [other].
   Plane.copy(Plane other)
     : _normal = Vector3.copy(other._normal),
       constant = other.constant;
 
+  /// Create a plane from normal components and a [constant].
   Plane.components(double x, double y, double z, this.constant)
     : _normal = Vector3(x, y, z);
 
+  /// Create a plane from a normal vector and a [constant].
   Plane.normalconstant(Vector3 normal_, this.constant)
     : _normal = Vector3.copy(normal_);
 
+  /// Copy the [normal] and [constant] from [o] into this.
   void copyFrom(Plane o) {
     _normal.setFrom(o._normal);
     constant = o.constant;
   }
 
+  /// Set the normal components and constant term of this plane.
   void setFromComponents(double x, double y, double z, double w) {
     _normal.setValues(x, y, z);
     constant = w;
   }
 
+  /// Normalize this plane so that [normal] has unit length.
   void normalize() {
     final inverseLength = 1.0 / normal.length;
     _normal.scale(inverseLength);
     constant *= inverseLength;
   }
 
+  /// Return the signed distance from [point] to this plane.
   double distanceToVector3(Vector3 point) => _normal.dot(point) + constant;
 }

lib/src/vector_math_geometry/filters/barycentric_filter.dart

@@ -4,6 +4,7 @@
 
 part of '../../../vector_math_geometry.dart';
 
+/// Adds barycentric coordinates for each triangle vertex in a mesh.
 class BarycentricFilter extends GeometryFilter {
   @override
   List<VertexAttrib> get generates => <VertexAttrib>[

lib/src/vector_math_geometry/filters/color_filter.dart

@@ -4,9 +4,12 @@
 
 part of '../../../vector_math_geometry.dart';
 
+/// Assigns a single color to every vertex in a mesh.
 class ColorFilter extends GeometryFilter {
+  /// The color written to each output vertex.
   Vector4 color;
 
+  /// Creates a filter that writes [color] into the mesh `COLOR` attribute.
   ColorFilter(this.color);
 
   @override

lib/src/vector_math_geometry/filters/flat_shade_filter.dart

@@ -4,6 +4,7 @@
 
 part of '../../../vector_math_geometry.dart';
 
+/// Expands a mesh to triangle vertices and generates flat-shaded normals.
 class FlatShadeFilter extends GeometryFilter {
   @override
   List<VertexAttrib> get requires => <VertexAttrib>[

lib/src/vector_math_geometry/filters/geometry_filter.dart

@@ -4,15 +4,23 @@
 
 part of '../../../vector_math_geometry.dart';
 
+/// A filter that produces a transformed copy of a [MeshGeometry].
 abstract class GeometryFilter {
+  /// Whether this filter supports in-place modification of a mesh.
   bool get inplace => false;
-  List<VertexAttrib> get requires => <VertexAttrib>[];
-  List<VertexAttrib> get generates => <VertexAttrib>[];
+
+  /// Vertex attributes that must be present on the input mesh.
+  List<VertexAttrib> get requires => const <VertexAttrib>[];
+
+  /// Vertex attributes that this filter guarantees on the output mesh.
+  List<VertexAttrib> get generates => const <VertexAttrib>[];
 
   /// Returns a copy of the mesh with any filter transforms applied.
   MeshGeometry filter(MeshGeometry mesh);
 }
 
+/// A [GeometryFilter] that can apply its transformation directly to a mesh
+/// in-place.
 abstract class InplaceGeometryFilter extends GeometryFilter {
   @override
   bool get inplace => true;

lib/src/vector_math_geometry/filters/invert_filter.dart

@@ -4,6 +4,7 @@
 
 part of '../../../vector_math_geometry.dart';
 
+/// Reverses triangle winding and flips normals for a mesh.
 class InvertFilter extends InplaceGeometryFilter {
   @override
   void filterInplace(MeshGeometry mesh) {

lib/src/vector_math_geometry/filters/transform_filter.dart

@@ -4,9 +4,12 @@
 
 part of '../../../vector_math_geometry.dart';
 
+/// Applies a matrix transform to each mesh position in-place.
 class TransformFilter extends InplaceGeometryFilter {
+  /// The transform applied to each position in the mesh.
   Matrix4 transform;
 
+  /// Creates a filter that transforms positions using [transform].
   TransformFilter(this.transform);
 
   @override