Documentation Review #1

* Review, edit and rewrite documentation for example.md and all models of the API.

Author: imaachman

example/example.md

@@ -4,25 +4,24 @@
 import 'package:codelessly_api/codelessly_api.dart';
 import 'package:json_annotation/json_annotation.dart';
 
-part 'my_cool_node.g.dart';
+part 'my_node.g.dart';
 
-/// At it's core, this is the most basic example of how to create a complete
-/// [BaseNode].
+/// An example of how to create a new node.
 @JsonSerializable()
-class MyCoolNode extends BaseNode {
+class MyNode extends BaseNode {
   @override
-  final String type = 'myCoolNode';
+  final String type = 'myNode';
 
-  MyCoolNode({
+  MyNode({
     required super.id,
     required super.name,
     required super.basicBoxLocal,
   });
 
-  factory MyCoolNode.fromJson(Map json) => _$MyCoolNodeFromJson(json);
+  factory MyNode.fromJson(Map json) => _$MyNodeFromJson(json);
 
   @override
-  Map toJson() => _$MyCoolNodeToJson(this);
+  Map toJson() => _$MyNodeToJson(this);
 }
 
 ```

lib/src/api/models/action/action.dart

@@ -10,7 +10,7 @@ part 'action.g.dart';
 
 /// Type of the action to perform on a user interaction.
 enum ActionType {
-  /// Navigate to something.
+  /// Navigate to a page.
   navigation,
 
   /// Open a link.
@@ -28,7 +28,7 @@ enum ActionType {
   /// Call a custom function.
   callFunction;
 
-  /// Displayable string representation of the action type.
+  /// Displayable string representation of the [ActionType].
   String get prettify {
     switch (this) {
       case ActionType.navigation:
@@ -47,8 +47,6 @@ enum ActionType {
   }
 }
 
-/// ActionModel is named that way to not conflict with 'Action' from
-/// Material file.
 /// Holds information about an action to perform on a user interaction.
 @JsonSerializable()
 class ActionModel with SerializableMixin {

lib/src/api/models/action/link_action.dart

@@ -10,10 +10,10 @@ import 'action.dart';
 
 part 'link_action.g.dart';
 
-/// An action that navigates/opens a link.
+/// An action that opens up a link.
 @JsonSerializable()
 class LinkAction extends ActionModel with EquatableMixin, SerializableMixin {
-  /// The link to navigate to.
+  /// The link to open.
   final String url;
 
   /// Creates a new [LinkAction] with the given data.

lib/src/api/models/action/navigation_action.dart

@@ -12,7 +12,7 @@ part 'navigation_action.g.dart';
 
 /// Defines how the navigation should be performed.
 enum NavigationType {
-  /// Navigate to a specified page.
+  /// Navigate to the specified page.
   push,
 
   /// Navigate back from the current page.
@@ -21,7 +21,7 @@ enum NavigationType {
   /// Replace the current page with the specified page in the navigation stack.
   replace;
 
-  /// Displayable string representation of the action type.
+  /// Displayable string representation of [NavigationType].
   String get prettify {
     switch (this) {
       case NavigationType.push:
@@ -34,15 +34,14 @@ enum NavigationType {
   }
 }
 
-/// An action that navigates to a new route.
+/// An action that navigates to a new page.
 @JsonSerializable()
 class NavigationAction extends ActionModel
     with EquatableMixin, SerializableMixin {
   /// Defines how the navigation should be performed.
   final NavigationType navigationType;
 
-  /// Destination nodeID. Typically, a canvas, dialog or bottom sheet.
-  // TODO: Rename to "destination".
+  /// Destination canvas node's ID.
   final String destinationId;
 
   /// Creates a new [NavigationAction].

lib/src/api/models/action/set_value_action.dart

@@ -10,14 +10,14 @@ import 'action.dart';
 
 part 'set_value_action.g.dart';
 
-/// An action that sets a value to a property on a node.
+/// An action that sets value of a property of the node.
 @JsonSerializable()
 class SetValueAction extends ActionModel
     with EquatableMixin, SerializableMixin {
-  /// ID of the node to set the value on.
+  /// ID of the node whose values are to be set.
   final String nodeID;
 
-  /// Values to set on the node.
+  /// List of values to be set in the node.
   @JsonKey(fromJson: valuesFromJson)
   final List<ValueModel> values;
 
@@ -52,14 +52,19 @@ enum SetValueMode {
   /// Sets the value directly.
   discrete,
 
-  /// Toggles the value before setting it. Only applies to toggleable values
-  /// like booleans.
+  /// Toggles the value before setting it.
+  /// Only applicable on toggleable values, such as booleans.
   toggle,
 
-  ///
+  /// Syncs the value with the internal value of the node that is performing the
+  /// action. [syncValue] works only if both the values are of same type.
+  /// For example, if a checkbox node is performing an action to change the
+  /// visibility of a node, the visibility will sync with checkbox's internal
+  /// value, i.e., [checked -> visible] and [unchecked -> invisible].
+  /// In this case, both the values are of type [bool].
   syncValue;
 
-  /// Displayable string representation of this enum.
+  /// Displayable string representation of [SetValueMode].
   String get prettify {
     switch (this) {
       case SetValueMode.discrete:
@@ -72,9 +77,9 @@ enum SetValueMode {
   }
 }
 
-/// Represents a value to set on a node.
+/// Represents a value to set in a node.
 abstract class ValueModel<T> with SerializableMixin {
-  /// The name of the property to set the value on.
+  /// The name of the property to set the value of.
   final String name;
 
   /// Describes how to set the value.
@@ -111,7 +116,7 @@ abstract class ValueModel<T> with SerializableMixin {
 List<ValueModel> valuesFromJson(List values) =>
     values.map((value) => ValueModel.fromJson(value)).toList();
 
-/// A boolean type of value.
+/// Value of boolean type.
 @JsonSerializable()
 class BoolValue extends ValueModel<bool?> with SerializableMixin {
   /// Whether this property is nullable.
@@ -146,7 +151,7 @@ class BoolValue extends ValueModel<bool?> with SerializableMixin {
   Map toJson() => _$BoolValueToJson(this);
 }
 
-/// An integer type of value.
+/// Value of integer type.
 @JsonSerializable()
 class IntValue extends ValueModel<int> with SerializableMixin {
   /// Creates a new [IntValue].
@@ -158,7 +163,8 @@ class IntValue extends ValueModel<int> with SerializableMixin {
     assert(mode != SetValueMode.toggle, '${mode.prettify} mode not supported.');
   }
 
-  /// Creates a new [IntValue] where the default value is 0 and mode is discrete.
+  /// Creates a new [IntValue] where the default value is 0 and mode is
+  /// discrete.
   const IntValue.discreteZero({
     required super.name,
     super.value = 0,
@@ -183,7 +189,7 @@ class IntValue extends ValueModel<int> with SerializableMixin {
   Map toJson() => _$IntValueToJson(this);
 }
 
-/// A double type of value.
+/// Value of double type.
 @JsonSerializable()
 class DoubleValue extends ValueModel<double> with SerializableMixin {
   /// Creates a new [DoubleValue].
@@ -195,7 +201,8 @@ class DoubleValue extends ValueModel<double> with SerializableMixin {
     assert(mode != SetValueMode.toggle, '${mode.prettify} mode not supported.');
   }
 
-  /// Creates a new [DoubleValue] where the default value is 0 and mode is discrete.
+  /// Creates a new [DoubleValue] where the default value is 0 and mode is
+  /// discrete.
   const DoubleValue.discreteZero({
     required super.name,
     super.value = 0,
@@ -220,7 +227,7 @@ class DoubleValue extends ValueModel<double> with SerializableMixin {
   Map toJson() => _$DoubleValueToJson(this);
 }
 
-/// A string type of value.
+/// Value of string type.
 @JsonSerializable()
 class StringValue extends ValueModel<String> with SerializableMixin {
   /// Creates a new [StringValue].

lib/src/api/models/action/submit_action.dart

@@ -10,12 +10,12 @@ import 'action.dart';
 
 part 'submit_action.g.dart';
 
-/// Represents supported service for submit action.
+/// Represents supported services for submit action.
 enum SubmitActionService {
-  /// Mailchimp service for submit action.
+  /// Mailchimp service.
   mailchimp;
 
-  /// Displayable string representation of the service.
+  /// Displayable string representation of [SubmitActionService].
   String get prettify {
     switch (this) {
       case SubmitActionService.mailchimp:
@@ -27,13 +27,13 @@ enum SubmitActionService {
 /// An action that submits a form.
 @JsonSerializable()
 class SubmitAction extends ActionModel with EquatableMixin, SerializableMixin {
-  /// Submit service to use.
+  /// Service used to submit the form.
   SubmitActionService service;
 
-  /// ID of the text field node to submit.
+  /// ID of the text field node whose content needs to be submitted.
   final String primaryTextField;
 
-  /// API key for for the submit service.
+  /// API key used to access the service.
   final String apiKey;
 
   /// Creates a new [SubmitAction].
@@ -73,11 +73,11 @@ class MailchimpSubmitAction extends SubmitAction {
   final String listID;
 
   /// Optional field to store the first name of the subscriber.
-  /// It referes to the ID of a text field node.
+  /// It refers to the ID of a text field node.
   final String firstNameField;
 
   /// Optional field to store the last name of the subscriber.
-  /// It referes to the ID of a text field node.
+  /// It refers to the ID of a text field node.
   final String lastNameField;
 
   /// Creates a new [MailchimpSubmitAction].

lib/src/api/models/alignment.dart

@@ -9,17 +9,8 @@ import '../mixins.dart';
 
 part 'alignment.g.dart';
 
-/// AlignmentModel wraps AlignmentData.
-/// Having a nullable node property causes issues in the app.
-/// The most severe case was with undoManager.registerActionEnd not knowing
-/// if the alignment was updated or not, as it uses null for missing values
-/// but on alignment, null is a valid option. On Paint there was the same issue,
-/// alignment was an optional property and there was no way to know if its value
-/// was null or its value wasn't there.
-///
-/// Even though in nodes constructor the alignment property is nullable,
-/// their inner property is not (see mixins.dart).
-/// If it is null, it gets assigned AlignmentModel.none.
+/// [AlignmentModel] wraps [AlignmentData] and provides standard alignment
+/// values such as [topRight] and [bottomCenter] for ease of use.
 @JsonSerializable()
 class AlignmentModel with EquatableMixin, SerializableMixin {
   /// Holds the actual x and y percentage information.
@@ -131,7 +122,7 @@ class AlignmentModel with EquatableMixin, SerializableMixin {
   static const AlignmentModel bottomRight =
       AlignmentModel(AlignmentData(1.0, 1.0));
 
-  /// Whether this alignment one of the [values].
+  /// Whether this alignment is one of the [values].
   bool get isStandard => values.contains(this);
 
   /// Whether this alignment is one of the standard alignments that represent
@@ -159,10 +150,9 @@ class AlignmentModel with EquatableMixin, SerializableMixin {
     AlignmentModel.none,
   ];
 
-  /// Allows to create a new instance of this class by copying the current
-  /// instance and replacing the given fields with the new values.
+  /// Duplicates this [AlignmentModel] with given data overrides.
   AlignmentModel copyWith({AlignmentData? data}) {
-    return AlignmentModel(data ?? this.data); // Deep copy.
+    return AlignmentModel(data ?? this.data);
   }
 
   @override
@@ -198,7 +188,7 @@ class AlignmentModel with EquatableMixin, SerializableMixin {
   }
 }
 
-/// A data class that holds the x and y values of an alignment.
+/// A data class that holds the x and y values of the alignment.
 @JsonSerializable()
 class AlignmentData extends Equatable with SerializableMixin {
   /// The x value of the alignment that represents how far it is from
@@ -217,8 +207,7 @@ class AlignmentData extends Equatable with SerializableMixin {
   @override
   List<Object?> get props => [x, y];
 
-  /// Allows to create new instance of this class by copying the current
-  /// instance and replacing the given fields with the new values.
+  /// Duplicates this [AlignmentData] with given data overrides.
   AlignmentData copyWith({double? x, double? y}) =>
       AlignmentData(x ?? this.x, y ?? this.y);