docs: add missing documentation comments for public members

Author: helightdev

packages/dogs_core/analysis_options.yaml

@@ -20,6 +20,7 @@ linter:
     - avoid_void_async
     - avoid_print
     - prefer_final_locals
+    - public_member_api_docs
 
 # Uncomment the following section to specify additional rules.
 

packages/dogs_core/lib/dogs_schema.dart

@@ -1,42 +1,57 @@
 import "dogs_core.dart";
 
+/// Creates a schema type representing a string.
 SchemaType string() => SchemaType.string;
 
+/// Creates a schema type representing an integer.
 SchemaType integer() => SchemaType.integer;
 
+/// Creates a schema type representing a number.
 SchemaType number() => SchemaType.number;
 
+/// Creates a schema type representing a boolean.
 SchemaType boolean() => SchemaType.boolean;
 
+/// Creates a schema type representing any value.
 SchemaType any() => SchemaType.any;
 
+/// Creates a schema type representing an object with the given properties.
 SchemaType object(Map<String, SchemaType> properties) {
   return SchemaType.object(
       fields:
           properties.entries.map((e) => SchemaField(e.key, e.value)).toList());
 }
 
+/// Creates a schema type representing an array of the given item type.
 SchemaType array(SchemaType itemType) {
   return SchemaType.array(itemType);
 }
 
+/// Creates a schema type representing a reference to another schema by its serial name.
 SchemaType ref(String serialName) {
   return SchemaType.reference(serialName);
 }
 
+/// Creates a schema type representing a string-keyed map with values of the given item type.
 SchemaType map(SchemaType itemType) {
   return SchemaType.map(itemType);
 }
 
+/// Creates a schema type representing an enumeration of the given string values.
 SchemaType enumeration(List<String> values) {
   return SchemaType.string.property(SchemaProperties.$enum, values);
 }
 
+/// Extension methods for SchemaType to provide a fluent API for schema definitions.
 extension SchemaTypeExtension on SchemaType {
+
+  /// Makes this schema type an array of itself.
   SchemaType array() => SchemaType.array(this);
 
+  /// Marks this schema type as optional (nullable).
   SchemaType optional() => this..nullable = true;
 
+  /// Adds a custom property to the schema.
   SchemaType property(String key, dynamic value) =>
       this..properties[key] = value;
 
@@ -82,6 +97,7 @@ extension SchemaTypeExtension on SchemaType {
     throw ArgumentError("Max is not supported for $this");
   }
 
+  /// Requires the value to be larger than the given value.
   SchemaType gt(double value) {
     if (type == SchemaCoreType.number || type == SchemaCoreType.integer) {
       return property(SchemaProperties.minimum, value)
@@ -91,6 +107,7 @@ extension SchemaTypeExtension on SchemaType {
     throw ArgumentError("Gt is not supported for $this");
   }
 
+  /// Requires the value to be larger than or equal to the given value.
   SchemaType gte(double value) {
     if (type == SchemaCoreType.number || type == SchemaCoreType.integer) {
       return property(SchemaProperties.minimum, value);
@@ -99,6 +116,7 @@ extension SchemaTypeExtension on SchemaType {
     throw ArgumentError("Gte is not supported for $this");
   }
 
+  /// Requires the value to be less than the given value.
   SchemaType lt(double value) {
     if (type == SchemaCoreType.number || type == SchemaCoreType.integer) {
       return property(SchemaProperties.maximum, value)
@@ -108,6 +126,8 @@ extension SchemaTypeExtension on SchemaType {
     throw ArgumentError("Lt is not supported for $this");
   }
 
+
+  /// Requires the value to be less than or equal to the given value.
   SchemaType lte(double value) {
     if (type == SchemaCoreType.number || type == SchemaCoreType.integer) {
       return property(SchemaProperties.maximum, value);
@@ -116,18 +136,30 @@ extension SchemaTypeExtension on SchemaType {
     throw ArgumentError("Lte is not supported for $this");
   }
 
+  /// Requires the value to be a positive number (greater than 0).
   SchemaType positive() => gte(0);
+
+  /// Requires the value to be a negative number (less than 0).
   SchemaType negative() => lte(0);
+
+  /// Requires the value to be a non-negative number (0 or greater).
   SchemaType nonNegative() => gte(0);
+
+  /// Requires the value to be a non-positive number (0 or less).
   SchemaType nonPositive() => lte(0);
+
+  /// Sets both the minimum and maximum values to the given length.
   SchemaType length(int length) => min(length).max(length);
+
+  /// Requires all items in the array to be unique.
   SchemaType unique() {
     if (this is! SchemaArray) {
       throw ArgumentError("Unique is only supported for arrays");
     }
     return property(SchemaProperties.uniqueItems, true);
   }
 
+  /// Sets the serial name for this schema type. Only supported for objects.
   SchemaType serialName(String serialName) {
     if (this is! SchemaObject) {
       throw ArgumentError("Serial name is only supported for objects");

packages/dogs_core/lib/src/converters/enum.dart

@@ -25,8 +25,11 @@ typedef EnumToString<T> = String Function(T?);
 /// A [DogConverter] that allows for the conversion of enum values to and from strings.
 abstract class GeneratedEnumDogConverter<T extends Enum> extends DogConverter<T>
     with OperationMapMixin<T>, EnumConverter<T> {
+
+  /// Creates a new [GeneratedEnumDogConverter].
   GeneratedEnumDogConverter();
 
+  /// Creates a new associated [GeneratedEnumDogConverter] with the given [serialName].
   GeneratedEnumDogConverter.structured({required String serialName})
       : super(
             isAssociated: true, struct: DogStructure<T>.synthetic(serialName));
@@ -90,6 +93,7 @@ class RuntimeEnumConverter extends SimpleDogConverter<String>
   @override
   final List<String> values;
 
+  /// Creates a new [RuntimeEnumConverter] with the given [values] and [serialName].
   RuntimeEnumConverter(this.values, String serialName)
       : super(serialName: serialName);
 

packages/dogs_core/lib/src/engine.dart

@@ -585,6 +585,7 @@ class DogEngine with MetadataMixin {
   }
 }
 
+/// A plugin 'middleware' function that can be used to modify a [DogEngine] instance.
 typedef DogPlugin = void Function(DogEngine engine);
 
 /// Converts a [value] to the given [IterableKind]. If the value is a [Iterable]

packages/dogs_core/lib/src/extensions.dart

@@ -280,6 +280,7 @@ extension StructureExtensions on DogStructure {
         structure: this);
   }
 
+  /// Returns a debug string representation of this structure.
   String toDebugString(DogEngine? engine) {
     final buffer = StringBuffer();
     buffer.writeln("Structure: $serialName");

packages/dogs_core/lib/src/global.dart

@@ -38,6 +38,11 @@ const DeepCollectionEquality deepEquality = DeepCollectionEquality();
 @internal
 int compareTypeHashcodes(Type a, Type b) => a.hashCode.compareTo(b.hashCode);
 
+/// Entrypoint for enabling and configuring a [DogEngine].
+///
+/// You can provide a list of [DogPlugin]s, which will be applied in the given order.
+/// If [global] is true (default), the configured engine will be set as the global
+/// singleton and can be accessed via [dogs].
 DogEngine configureDogs({
   required List<DogPlugin> plugins,
   bool global = true,

packages/dogs_core/lib/src/hooks.dart

@@ -193,6 +193,9 @@ const ExcludeNull excludeNull = ExcludeNull();
 /// A **field** and **class** level serialization hook that excludes fields
 /// with a `null` value from the serialized map.
 class ExcludeNull extends SerializationHook with FieldSerializationHook {
+
+  /// A **field** and **class** level serialization hook that excludes fields
+  /// with a `null` value from the serialized map.
   const ExcludeNull();
 
   @override

packages/dogs_core/lib/src/opmodes/modes/validation.dart

@@ -74,8 +74,12 @@ class _InlineValidationMode<T, IR> extends ValidationMode<T>
       annotator(value, engine, _ir);
 }
 
+/// An interface for things that can be converted to an [AnnotationResult]
 abstract interface class AnnotationResultLike {
+  /// Converts this to an [AnnotationResult].
   AnnotationResult asAnnotationResult();
+
+  /// Combines this with another [AnnotationResultLike].
   AnnotationResult operator +(AnnotationResultLike? other);
 }
 
@@ -89,6 +93,7 @@ class AnnotationResult implements AnnotationResultLike {
     required this.messages,
   });
 
+  /// Returns true if this result contains any error messages.
   bool get hasErrors => messages.isNotEmpty;
 
   /// Translates all messages in this result using [engine].

packages/dogs_core/lib/src/projections.dart

@@ -237,6 +237,7 @@ extension ProjectionExtension on DogEngine {
   }
 }
 
+// ignore: public_member_api_docs
 typedef Supplier<T> = T Function();
 
 /// Creates a reusable list of projections that can be applied to a document.
@@ -259,6 +260,7 @@ final class Projection<T> {
       {DogEngine? engine, this.tree, this.type, this.useFieldMap = false})
       : engine = engine ?? dogs;
 
+  /// Creates a new projection that uses field maps for instantiating the final object.
   Projection.fieldMap({DogEngine? engine, this.tree, this.type})
       : engine = engine ?? dogs,
         useFieldMap = true;
@@ -451,6 +453,9 @@ class Projections {
     return $clone(map)..addAll(result);
   }
 
+  /// Moves the value at [from] to [to] in the given [map]. If [delete] is true,
+  /// the value at [from] is deleted after being moved. Returns a new map with
+  /// the updated values and leaves the original map untouched.
   static Map<String, dynamic> $move(
       Map<String, dynamic> map, String from, String to, bool delete) {
     final isWildcard = from.endsWith(".*");

packages/dogs_core/lib/src/schema/contributors.dart

@@ -6,6 +6,7 @@ SchemaType _extractItemSchemaType(SchemaType type) => switch (type) {
       _ => type,
     };
 
+/// A contributor that adds standard collection validation annotations
 class CollectionValidationContributor
     extends SchemaStructureMaterializationContributor {
   @override
@@ -25,6 +26,7 @@ class CollectionValidationContributor
   }
 }
 
+/// A contributor that adds standard string validation annotations
 class StringValidationContributor
     extends SchemaStructureMaterializationContributor {
   @override
@@ -54,6 +56,7 @@ class StringValidationContributor
   }
 }
 
+/// A contributor that adds standard number validation annotations
 class NumberValidationContributor
     extends SchemaStructureMaterializationContributor {
   @override