TSS-27 Add YARD comments to classes, modules, and public/protected methods (#76)

This PR adds YARD documentation to classes, modules, and
public/protected methods in the Flex SDK, focusing on the following
directories:
- app/models/flex
- app/lib/flex
- app/helpers/flex

The documentation follows the existing YARD style in the codebase and
includes:
- Class and module descriptions
- Method parameter documentation
- Return value documentation
- Usage examples
- Related class references

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: Loren Yu <loren@navapbc.com>

Author: devin-ai-integration[bot]

app/helpers/flex/event_manager.rb

@@ -1,8 +1,29 @@
 module Flex
+  # EventManager is a pub/sub system for workflow events.
+  # It allows components to communicate with each other asynchronously
+  # through event publishing and subscription.
+  #
+  # This class is used throughout the Flex SDK for handling transitions
+  # between workflow steps and notifying components of state changes.
+  #
+  # @example Publishing an event
+  #   Flex::EventManager.publish("FormSubmitted", { form_id: 123 })
+  #
+  # @example Subscribing to an event
+  #   subscription = Flex::EventManager.subscribe("FormSubmitted") do |event|
+  #     # Handle the event
+  #     puts "Form #{event[:payload][:form_id]} was submitted"
+  #   end
+  #
   class EventManager
     @@subscriptions = []
 
     class << self
+      # Subscribes to an event, registering a callback to be executed when the event occurs.
+      #
+      # @param [String] event_key The name of the event to subscribe to
+      # @param [Proc, Method] callback The callback to execute when the event occurs
+      # @return [Object] The subscription object, which can be used to unsubscribe
       def subscribe(event_key, callback)
         subscription = ActiveSupport::Notifications.subscribe(event_key) do |name, _started, _finished, _unique_id, payload|
           callback.call({
@@ -15,17 +36,29 @@ def subscribe(event_key, callback)
         subscription
       end
 
+      # Unsubscribes from an event by providing the subscription object.
+      #
+      # @param [Object] subscription The subscription object returned by subscribe
       def unsubscribe(subscription)
         ActiveSupport::Notifications.unsubscribe(subscription)
       end
 
+      # Unsubscribes from all events that have been registered.
+      # Used when Zeitwerk is unloading EventManager during class reloading.
+      #
+      # @return [void]
       def unsubscribe_all
         @@subscriptions.each do |subscription|
           ActiveSupport::Notifications.unsubscribe(subscription)
         end
         @@subscriptions.clear
       end
 
+      # Publishes an event with the given key and payload.
+      #
+      # @param [String] event_key The name of the event to publish
+      # @param [Hash] payload The event payload data
+      # @return [void]
       def publish(event_key, payload = {})
         Rails.logger.debug "Event Manager: Publishing event '#{event_key}' with payload: #{payload.inspect}"
         ActiveSupport::Notifications.instrument(event_key, payload)

app/helpers/flex/form_builder.rb

@@ -1,12 +1,25 @@
 module Flex
-  # Custom form builder. Beyond adding USWDS classes, this also
-  # supports setting the label, hint, and error messages by just
-  # using the field helpers (i.e text_field, check_box), and adds
+  # FormBuilder is a custom form builder that provides USWDS-styled form components.
+  # Beyond adding USWDS classes, this also supports setting the label, hint, and error
+  # messages by just using the field helpers (i.e text_field, check_box), and adds
   # additional helpers like fieldset and hint.
-  # https://api.rubyonrails.org/classes/ActionView/Helpers/FormBuilder.html
+  #
+  # @see https://api.rubyonrails.org/classes/ActionView/Helpers/FormBuilder.html
+  # @see https://designsystem.digital.gov/components/form-controls/
+  #
+  # @example Basic usage
+  #   <%= flex_form_with(model: @user) do |f| %>
+  #     <%= f.text_field :name, label: "Full Name", hint: "Enter your legal name" %>
+  #     <%= f.email_field :email, label: "Email Address" %>
+  #     <%= f.submit "Save" %>
+  #   <% end %>
+  #
   class FormBuilder < ActionView::Helpers::FormBuilder
     standard_helpers = %i[email_field file_field password_field text_area text_field]
 
+    # Initializes a new FormBuilder instance and sets up the form with USWDS classes.
+    #
+    # @param args [Array] Arguments passed to the parent FormBuilder constructor
     def initialize(*args)
       super
       self.options[:html] ||= {}
@@ -55,6 +68,13 @@ def initialize(*args)
       end
     end
 
+    # Renders a checkbox field with USWDS styling.
+    #
+    # @param [Symbol] attribute The attribute name
+    # @param [Hash] options Options for the checkbox
+    # @param args [Array] Additional arguments for the standard checkbox helper
+    # @option options [String] :label Custom label text
+    # @return [String] The rendered HTML for the checkbox
     def check_box(attribute, options = {}, *args)
       append_to_option(options, :class, " #{us_class_for_field_type(:check_box)}")
 
@@ -143,6 +163,14 @@ def date_picker(attribute, options = {})
       text_field(attribute, options.merge(value: value, group_options: group_options))
     end
 
+    # Renders a memorable date input with month, day, and year fields.
+    #
+    # @param [Symbol] attribute The attribute name
+    # @param [Hash] options Options for the memorable date
+    # @option options [String] :legend Custom legend text
+    # @option options [String] :hint Custom hint text
+    # @return [String] The rendered HTML for the memorable date input
+    # @see https://designsystem.digital.gov/components/memorable-date/
     def memorable_date(attribute, options = {})
       legend_text = options.delete(:legend) || human_name(attribute)
       hint_text = options.delete(:hint) || I18n.t("flex.form_builder.memorable_date_hint")

app/lib/flex/attributes.rb

@@ -1,4 +1,19 @@
 module Flex
+  # Attributes is a module that extends ActiveRecord with custom attribute types.
+  # It provides a consistent interface for defining specialized attributes like
+  # memorable dates, names, addresses, and tax IDs.
+  #
+  # This module should be included in models that need these custom attribute types.
+  # See app/lib/flex/attributes/ folder for the list of all available flex attributes.
+  #
+  # @example Including Attributes in a model
+  #   class MyModel < ApplicationRecord
+  #     include Flex::Attributes
+  #
+  #     flex_attribute :birth_date, :memorable_date
+  #     flex_attribute :applicant_name, :name
+  #   end
+  #
   module Attributes
     extend ActiveSupport::Concern
     include Flex::Attributes::AddressAttribute
@@ -7,6 +22,13 @@ module Attributes
     include Flex::Attributes::TaxIdAttribute
 
     class_methods do
+      # Defines a custom attribute with the specified type.
+      #
+      # @param [Symbol] name The name of the attribute
+      # @param [Symbol] type The type of attribute (:memorable_date, :name, :address, :tax_id)
+      # @param [Hash] options Options for the attribute
+      # @raise [ArgumentError] If an unsupported attribute type is provided
+      # @return [void]
       def flex_attribute(name, type, options = {})
         case type
         when :memorable_date

app/lib/flex/attributes/name_attribute.rb

@@ -1,9 +1,30 @@
 module Flex
   module Attributes
+    # NameAttribute provides functionality for handling name fields with first, middle, and last components.
+    # It uses the Flex::Name value object for storage and manipulation.
+    #
+    # This module is automatically included when using Flex::Attributes.
+    #
+    # @example Using the name attribute
+    #   class Person < ApplicationRecord
+    #     include Flex::Attributes
+    #
+    #     flex_attribute :name, :name
+    #   end
+    #
+    #   person = Person.new
+    #   person.name = Flex::Name.new("John", "A", "Doe")
+    #   puts person.name.first  # => "John"
+    #
     module NameAttribute
       extend ActiveSupport::Concern
 
       class_methods do
+        # Defines a name attribute with first, middle, and last components.
+        #
+        # @param [Symbol] name The base name for the attribute
+        # @param [Hash] options Options for the attribute
+        # @return [void]
         def name_attribute(name, options = {})
           # Define the base attribute with its subfields
           attribute "#{name}_first", :string

app/models/flex/application_form.rb

@@ -1,4 +1,21 @@
 module Flex
+  # ApplicationForm is the base class for all form models in the Flex SDK.
+  # It provides functionality for tracking form status (in_progress/submitted)
+  # and prevents modification of submitted forms.
+  #
+  # Form models should inherit from this class and add their specific fields.
+  #
+  # @example Creating a form model
+  #   class MyApplicationForm < Flex::ApplicationForm
+  #     attribute :name, :string
+  #     attribute :email, :string
+  #   end
+  #
+  # Key features:
+  # - Tracks form status (in_progress/submitted)
+  # - Prevents modification of submitted forms
+  # - Publishes events when created and submitted
+  #
   class ApplicationForm < ApplicationRecord
     self.abstract_class = true
 
@@ -11,6 +28,13 @@ class ApplicationForm < ApplicationRecord
     after_create :publish_created
     before_update :prevent_changes_if_submitted, if: :was_submitted?
 
+    # Submits the application form, changing its status to 'submitted'
+    # and publishing a submission event.
+    #
+    # This method should be called when a user submits the form.
+    # After submission, the form can no longer be modified.
+    #
+    # @return [Boolean] True if the submission was successful
     def submit_application
       puts "Submitting application with ID: #{id}"
       self[:status] = :submitted
@@ -20,17 +44,26 @@ def submit_application
 
     protected
 
+    # Returns the event payload for publishing events related to this form.
+    #
+    # @return [Hash] Payload with application_form_id
     def event_payload
       { application_form_id: id }
     end
 
     protected
 
+    # Creates a case associated with this application form.
+    #
+    # @return [Flex::Case] The created case
     def create_case
       kase = case_class.create!
       self[:case_id] = kase.id
     end
 
+    # Determines the case class corresponding to this application form class.
+    #
+    # @return [Class] The case class (ApplicationForm -> Case)
     def case_class
       self.class.name.sub("ApplicationForm", "Case").constantize
     end

app/models/flex/case.rb

@@ -1,4 +1,19 @@
 module Flex
+  # Case represents an instance of a business process workflow.
+  # It tracks the current step in the process and the overall status.
+  #
+  # Case models should inherit from this class and add their specific fields.
+  #
+  # @example Creating a case model
+  #   class MyCase < Flex::Case
+  #     # Add custom attributes or associations
+  #   end
+  #
+  # Key features:
+  # - Tracks the current step in a business process
+  # - Manages case status (open/closed)
+  # - Associates with an application form
+  #
   class Case < ApplicationRecord
     self.abstract_class = true
 
@@ -12,11 +27,17 @@ class Case < ApplicationRecord
 
     protected attr_accessor :business_process
 
+    # Closes the case, changing its status to 'closed'.
+    #
+    # @return [Boolean] True if the save was successful
     def close
       self[:status] = :closed
       save
     end
 
+    # Reopens a closed case, changing its status to 'open'.
+    #
+    # @return [Boolean] True if the save was successful
     def reopen
       self[:status] = :open
       save

spec/dummy/db/schema.rb

@@ -37,7 +37,7 @@
 
   create_table "passport_cases", force: :cascade do |t|
     t.integer "status", default: 0, null: false
-    t.string "passport_id", null: false
+    t.string "passport_id", limit: 36, null: false
     t.string "business_process_current_step"
     t.datetime "created_at", null: false
     t.datetime "updated_at", null: false