ecs_on_rails 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bef233f6d1933696953db3058563f4e4178c67aeb6d56f6d2f241f64f23b81f3
-  data.tar.gz: a7806e71e299991ae122dd30ce78a009bf181ed55c11d8b43444be2a2f6ef1d8
+  metadata.gz: dc72bfa8de8f997d618f95ab47f65718fa60ba8bf81828ea8befa0501d8be45a
+  data.tar.gz: 96c83b903c33e4e490a8dd607f37fd8c4cfb87d1da0031fcef9d6d41888a5c60
 SHA512:
-  metadata.gz: 7fd3624f55f3264bbaf3c84cb355a63cc5e0e5e66eabd43d04ad01c1d87bff202dd8d4e851d6006c66c383c742702da548115161ab33dd2ddc7d1f37b0e86295
-  data.tar.gz: 926baa1d0cfca36f1453d0cc4abb02d463a04d49b499b2a6eb72f54534a4486ccfe27e1452a6b0a2206f2589062cd4f53aa1b05ab07fed7b4479e19515b92ecd
+  metadata.gz: 1a0125c3bad8212cf1aa1273ba18897afcf87fcf27f12acabd0586b5b62c8ba1f6b74c8a3a238ece5b707580d001dab95d68601bb16cd3ef9b235283e15e830d
+  data.tar.gz: 61f118b33194050f9f6eaa9976e43fef7d194074333307163052c24e388947c786dd17f9fa93451e368fe5af70b8a71928e8ef213cd0ece9fa8bbff4fd62cf09

data/.yardopts

@@ -0,0 +1,12 @@
+--markup markdown
+--markup-provider kramdown
+--readme README.md
+--title "ECS Rails - an Entity-Component-System reimagining of ActiveRecord"
+--charset utf-8
+--no-private
+--hide-void-return
+--embed-mixins
+lib/**/*.rb
+-
+CHANGELOG.md
+LICENSE.txt

data/CHANGELOG.md

@@ -6,6 +6,34 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.2.2] — 2026-07-23
+
+### Added
+
+- **YARD API documentation across the whole public API** — `@param`, `@return`,
+  `@raise`, `@example` and `@see` tags on every public module, class, attribute
+  and method (100% documented, verified by `yard stats`). The existing prose
+  rationale is kept; the tags are additive, so
+  [rubydoc.info/gems/ecs_on_rails](https://rubydoc.info/gems/ecs_on_rails) now
+  renders a real API reference rather than bare comments.
+- A `.yardopts`, shipped in the gem so rubydoc.info honours it. Notably
+  `--embed-mixins`, without which the DSL that `EcsRails::Entity` gains by
+  `extend`ing {EcsRails::DSL}, `Querying`, `Preloading` and `Relationships`
+  would not appear on `Entity` at all — which is where users look for it.
+- `documentation_uri` in the gemspec, pointing at the rubydoc.info API
+  reference. The narrative documentation (architecture, ADRs, RFCs) is reached
+  via the homepage and `source_code_uri`.
+
+### Fixed
+
+- `changelog_uri` in the gemspec pointed at `<repo>/blob/main/CHANGELOG.md`,
+  which 404s: the gem lives in `gem/` of a monorepo and there is no changelog at
+  the repo root, so the Changelog link on the 0.2.1 RubyGems page was broken.
+  Gem metadata is immutable once published, so this needed a release to correct.
+- `source_code_uri` now points at the `gem/` subtree rather than the repo root.
+
+No code change — 0.2.2 is identical to 0.2.1 apart from gemspec metadata.
+
 ## [0.2.1] — 2026-07-23
 
 First RubyGems release.

data/lib/ecs_rails/config.rb

@@ -12,9 +12,16 @@ module EcsRails
   # `entities_path` is the single knob. Components always live in a `components`
   # subdirectory of it, which is why `components_path` is derived rather than
   # separately settable — ADR-0010 deliberately exposes one path, not two.
+  # @example Restoring the pre-ADR-0010 single-directory layout
+  #   # config/initializers/ecs_rails.rb
+  #   EcsRails.configure { |config| config.entities_path = "app/models" }
+  #
+  # @see EcsRails.configure
   class Config
     # Entities land here; the default is the ADR-0010 layout. Set it to
-    # "app/models" to restore the pre-ADR-0010 single-directory layout.
+    # `"app/models"` to restore the pre-ADR-0010 single-directory layout.
+    #
+    # @return [String] the directory entities are generated into
     attr_accessor :entities_path
 
     def initialize
@@ -24,6 +31,12 @@ module EcsRails
     # Components live in a `components` subdirectory of the entities path. The
     # generated initializer collapses this directory so Zeitwerk treats the
     # `components/` segment as transparent (ADR-0010 "How it works").
+    #
+    # Derived rather than separately settable: ADR-0010 deliberately exposes one
+    # path, not two.
+    #
+    # @return [String] the directory components are generated into,
+    #   e.g. `"app/entities/components"`
     def components_path
       "#{entities_path}/components"
     end

data/lib/ecs_rails/dsl.rb

@@ -3,7 +3,7 @@
 module EcsRails
   # The class-level DSL that composes an entity out of components.
   #
-  # Implements RFC-0004. Extended into EcsRails::Entity, so every entity class —
+  # Implements RFC-0004. Extended into {EcsRails::Entity}, so every entity class —
   # and every subclass of one — answers `component`.
   #
   #   class User < ApplicationEntity
@@ -53,6 +53,36 @@ module EcsRails
     # an anonymous class on either side.
     #
     # Returns the Registry::Declaration.
+    #
+    # @example Composition, and the reader it generates
+    #   class User < ApplicationEntity
+    #     component Email
+    #   end
+    #
+    #   User.new.email           # => #<Email> — never nil
+    #
+    # @example Resolving a delegation conflict
+    #   component Group, except: [:title]
+    #
+    # @param component_class [Class<EcsRails::Component>] a concrete component
+    # @param only [Array<Symbol>, Symbol, nil] delegate only these methods.
+    #   Attribute aware: `:title` covers `#title` and `#title=`.
+    #   Mutually exclusive with `except:`.
+    # @param except [Array<Symbol>, Symbol, nil] delegate everything but these.
+    #   Attribute aware, as `only:` is. Mutually exclusive with `only:`.
+    # @return [EcsRails::Registry::Declaration] the recorded declaration
+    # @raise [EcsRails::InvalidComponent] if `component_class` is not a concrete
+    #   {EcsRails::Component} subclass, or is abstract and so owns no table
+    # @raise [EcsRails::DuplicateComponent] if this entity, or one it inherits
+    #   from, already declares this component (ADR-0005)
+    # @raise [EcsRails::DelegationConflict] if a delegated name is already
+    #   delegated by a sibling component, or collides with a component reader
+    #   (ADR-0004)
+    # @raise [ArgumentError] if both `only:` and `except:` are given, if either
+    #   names a method the component does not delegate, or if either class is
+    #   anonymous
+    # @see #components
+    # @see EcsRails::Presence::Entity#has? the `<reader>?` predicate this generates
     def component(component_class, only: nil, except: nil)
       validate_component_class!(component_class)
       options = normalized_delegation_options(only: only, except: except)
@@ -92,6 +122,16 @@ module EcsRails
     end
 
     # Every component this entity is composed from, nearest ancestor last.
+    #
+    # Inherited components are included: a subclass is composed from its parents'
+    # components as well as its own.
+    #
+    # @example
+    #   User.components  # => [Name, Email, Group]
+    #
+    # @return [Array<Class<EcsRails::Component>>] the component classes, resolved
+    #   live from the registry (so a reloaded constant is picked up)
+    # @see #component_declarations
     def components
       component_declarations.map(&:component_class)
     end
@@ -109,6 +149,11 @@ module EcsRails
     #
     # So EcsRails.registry.components_for(Admin) is only Admin's own, by design,
     # and this is the method that answers "what is an Admin made of".
+    #
+    # @return [Array<EcsRails::Registry::Declaration>] declarations, ancestors'
+    #   first, in declaration order. Carries the `only:`/`except:` options that
+    #   {#components} discards.
+    # @see #components
     def component_declarations
       entity_ancestry.flat_map { |klass| EcsRails.registry.components_for(klass) }
     end
@@ -134,6 +179,10 @@ module EcsRails
     # of DSL calls that can invert it. That is an ActiveRecord internal, so the
     # ordering is pinned by tests ("the generated methods module" in
     # spec/dsl_spec.rb) and an upgrade that changed it would fail loudly.
+    #
+    # @return [Module] the per-class module holding generated readers, delegated
+    #   methods and presence predicates
+    # @api private
     def generated_component_methods
       @generated_component_methods ||= begin
         mod = const_set(:GeneratedComponentMethods, Module.new)

data/lib/ecs_rails/preloading.rb

@@ -46,6 +46,20 @@ module EcsRails
     #
     # Built from `all` — like Querying — so it chains onto any prior scope and
     # keeps the entity-model default scope (ADR-0002/ADR-0011).
+    #
+    # @example Every declared component
+    #   Post.published.includes_components
+    #
+    # @example A named subset, chained onto a component filter
+    #   Post.with_component(PublishState).includes_components(Title, Body)
+    #
+    # @param component_classes [Array<Class<EcsRails::Component>>] components to
+    #   preload; empty preloads every component the entity declares
+    # @return [ActiveRecord::Relation] chainable, entity-model scoped
+    # @raise [EcsRails::InvalidComponent] if any argument is not a component, or
+    #   is not declared on this entity — unlike {EcsRails::Querying#with_component},
+    #   which accepts any concrete component
+    # @see EcsRails::Relationships#includes_related for relationships
     def includes_components(*component_classes)
       declared = components
       targets = component_classes.empty? ? declared : component_classes

data/lib/ecs_rails/presence.rb

@@ -28,6 +28,16 @@ module EcsRails
   # component by the DSL, into generated_component_methods (see
   # EcsRails::DSL#define_component_predicate); it is just `has?(ThatComponent)`.
   module Presence
+    # The entity side of presence: `add` / `has?` / `remove`.
+    #
+    # Included into {EcsRails::Entity}, so every entity answers these. The
+    # per-component `<reader>?` predicate (`user.moderator?`) is generated by
+    # {EcsRails::DSL} and is exactly {#has?}.
+    #
+    # @example
+    #   user.add(Moderator)     # persist the row now (idempotent, validated)
+    #   user.has?(Moderator)    # => true
+    #   user.remove(Moderator)  # destroy the row (idempotent)
     module Entity
       extend ActiveSupport::Concern
 
@@ -41,6 +51,22 @@ module EcsRails
       # catching that. Validated: it uses `save!`, so `add(Email)` raises
       # RecordInvalid (address is required) while `add(Moderator)` always
       # succeeds. You cannot add an empty required component (ADR-0009).
+      #
+      # @example A marker, which the save cascade would never write
+      #   user.add(Moderator)     # INSERTs the row now
+      #   user.moderator?         # => true
+      #
+      # @example Validation still applies
+      #   user.add(Email)         # raises: Email#address is required
+      #
+      # @param component_class [Class<EcsRails::Component>] a component this
+      #   entity declares
+      # @return [EcsRails::Component] the persisted component instance
+      # @raise [EcsRails::InvalidComponent] if the entity does not declare it
+      # @raise [ActiveRecord::RecordInvalid] if the component is invalid — you
+      #   cannot add an empty required component (ADR-0009)
+      # @see #has?
+      # @see #remove
       def add(component_class)
         name = ecs_presence_reader(component_class)
 
@@ -68,6 +94,20 @@ module EcsRails
       # component dirtied-and-saved on this instance is present without a fresh
       # query — and otherwise issues a bare existence check (SELECT ... EXISTS),
       # a load of nothing.
+      #
+      # The DSL also generates a per-component predicate, so `user.moderator?`
+      # asks exactly this question.
+      #
+      # @example
+      #   user.has?(Moderator)  # => true
+      #   user.moderator?       # => the same question, generated per component
+      #
+      # @param component_class [Class<EcsRails::Component>] a component this
+      #   entity declares
+      # @return [Boolean] whether a persisted row exists
+      # @raise [EcsRails::InvalidComponent] if the entity does not declare it
+      # @see #add
+      # @see #remove
       def has?(component_class)
         name = ecs_presence_reader(component_class)
 
@@ -88,6 +128,17 @@ module EcsRails
       # Destroys the row for `component_class` if present, and resets the reader
       # to a virtual default instance — exactly RFC-0006's `component.destroy`
       # semantics. Idempotent when absent. Returns the entity (RFC-0009).
+      #
+      # @example
+      #   user.remove(Moderator)  # DELETEs the row; no-op if there was none
+      #   user.moderator          # => #<Moderator> — virtual again, not nil
+      #
+      # @param component_class [Class<EcsRails::Component>] a component this
+      #   entity declares
+      # @return [self] the entity, for chaining
+      # @raise [EcsRails::InvalidComponent] if the entity does not declare it
+      # @see #add
+      # @see #has?
       def remove(component_class)
         name = ecs_presence_reader(component_class)
 

data/lib/ecs_rails/querying.rb

@@ -38,16 +38,48 @@ module EcsRails
     # Entities that HAVE a row for `component_class` (RFC-0010). With
     # `conditions`, the row must also match them (hash equality, like `where`).
     #
-    # Returns an ActiveRecord::Relation, chainable with `where`, `order`, `limit`,
-    # and further `with_component` / `without_component` calls (which AND).
+    # Compiles to a correlated `EXISTS` subquery, so an entity matches once —
+    # never duplicated as a join would. Condition values are sanitised by
+    # ActiveRecord and treated as data, never SQL (ADR-0011).
+    #
+    # The component need *not* be declared on this entity: querying a component
+    # the entity never declares is a valid, always-empty query, not an error.
+    #
+    # @example Filtering by a component's attributes
+    #   Post.with_component(PublishState, state: "published")
+    #
+    # @example Chaining — each call ANDs
+    #   Post.with_component(Title).with_component(Body).order(created_at: :desc)
+    #
+    # @param component_class [Class<EcsRails::Component>] a concrete component
+    # @param conditions [Hash] optional attribute equality the row must match
+    # @return [ActiveRecord::Relation] chainable, and still scoped to this
+    #   entity's own `model` discriminator (ADR-0002)
+    # @raise [EcsRails::InvalidComponent] if `component_class` is not a concrete
+    #   component, or is abstract and so owns no table
+    # @see #without_component
+    # @see EcsRails::Relationships#with_related the relationship-name equivalent
     def with_component(component_class, **conditions)
       all.where(ecs_component_exists_sql(component_class, conditions, negate: false))
     end
 
-    # Entities that have NO row for `component_class` (RFC-0010). No conditions
-    # form — "without a *matching* row" is ambiguous and unneeded (see the RFC's
-    # Non-goals). A virtual/lazy component has no row, so it counts as absent,
-    # which is the intuitive reading of "without" (ADR-0009).
+    # Entities that have NO row for `component_class` (RFC-0010).
+    #
+    # Compiles to `NOT EXISTS`, which is the NULL-safe form of "without" — unlike
+    # `NOT IN` or a `LEFT JOIN ... IS NULL`.
+    #
+    # There is deliberately no conditions form: "without a *matching* row" is
+    # ambiguous (see the RFC's Non-goals). A virtual/lazy component has no row, so
+    # it counts as absent — the intuitive reading of "without" (ADR-0009).
+    #
+    # @example
+    #   User.without_component(Avatar)
+    #
+    # @param component_class [Class<EcsRails::Component>] a concrete component
+    # @return [ActiveRecord::Relation] chainable, entity-model scoped
+    # @raise [EcsRails::InvalidComponent] if `component_class` is not a concrete
+    #   component, or is abstract and so owns no table
+    # @see #with_component
     def without_component(component_class)
       all.where(ecs_component_exists_sql(component_class, {}, negate: true))
     end

data/lib/ecs_rails/registry.rb

@@ -26,8 +26,17 @@ module EcsRails
     # every call, so a Declaration handed out before a reload still resolves to
     # the post-reload constants.
     class Declaration
+      # @!attribute [r] entity_class_name
+      #   @return [String] the declaring entity's class name
+      # @!attribute [r] component_class_name
+      #   @return [String] the declared component's class name
+      # @!attribute [r] options
+      #   @return [Hash] the frozen `only:`/`except:` delegation options
       attr_reader :entity_class_name, :component_class_name, :options
 
+      # @param entity_class_name [String] the declaring entity's class name
+      # @param component_class_name [String] the declared component's class name
+      # @param options [Hash] `only:`/`except:` delegation options
       def initialize(entity_class_name:, component_class_name:, options: {})
         @entity_class_name = entity_class_name
         @component_class_name = component_class_name
@@ -35,15 +44,25 @@ module EcsRails
         freeze
       end
 
-      # Raises NameError if the constant has gone away. See #components_for.
+      # Resolved live, so a reloaded constant is picked up.
+      #
+      # @return [Class<EcsRails::Entity>] the declaring entity class
+      # @raise [NameError] if the constant has gone away. See {Registry#components_for}.
       def entity_class
         entity_class_name.constantize
       end
 
+      # Resolved live, so a reloaded constant is picked up.
+      #
+      # @return [Class<EcsRails::Component>] the declared component class
+      # @raise [NameError] if the constant has gone away
       def component_class
         component_class_name.constantize
       end
 
+      # @param other [Object]
+      # @return [Boolean] true if both declare the same component on the same
+      #   entity with the same options
       def ==(other)
         other.is_a?(Declaration) &&
           entity_class_name == other.entity_class_name &&
@@ -52,10 +71,13 @@ module EcsRails
       end
       alias eql? ==
 
+      # @return [Integer] a hash consistent with {#==}, so Declarations work as
+      #   Hash keys and in Sets
       def hash
         [self.class, entity_class_name, component_class_name, options].hash
       end
 
+      # @return [String] e.g. `#<...Declaration User => Email {}>`
       def inspect
         "#<#{self.class} #{entity_class_name} => #{component_class_name} #{options.inspect}>"
       end
@@ -70,6 +92,15 @@ module EcsRails
     # Raises DuplicateComponent if this entity already declares this component —
     # per ADR-0005 a component appears at most once per entity, and RFC-0004
     # relies on the raise to catch a doubled `component` line at class-load time.
+    #
+    # @param entity_class [Class<EcsRails::Entity>] the declaring entity
+    # @param component_class [Class<EcsRails::Component>] the declared component
+    # @param options [Hash] `only:`/`except:` delegation options
+    # @return [Declaration] the recorded declaration
+    # @raise [EcsRails::DuplicateComponent] if this entity already declares this
+    #   component (ADR-0005)
+    # @raise [ArgumentError] if either class is anonymous, since the registry
+    #   keys entries by class name
     def register(entity_class:, component_class:, options: {})
       entity_name = name_for(entity_class)
       component_name = name_for(component_class)
@@ -98,12 +129,22 @@ module EcsRails
     # silently dropping the entry would make generators emit an incomplete schema
     # and delegation quietly stop working. #clear! is the supported way to drop
     # entries, and the Railtie calls it on every reload.
+    #
+    # Only the entity's *own* declarations — inheritance is walked on read by
+    # {EcsRails::DSL#component_declarations}, not copied down here.
+    #
+    # @param entity_class [Class<EcsRails::Entity>] the entity to look up
+    # @return [Array<Declaration>] its declarations; empty if none
     def components_for(entity_class)
       declarations = @declarations[name_for(entity_class)]
       declarations ? declarations.dup : []
     end
 
     # Every entity class declaring this component, as live class objects.
+    #
+    # @param component_class [Class<EcsRails::Component>] the component
+    # @return [Array<Class<EcsRails::Entity>>] the entities composed from it
+    # @raise [NameError] if a recorded entity constant has gone away
     def entities_for(component_class)
       component_name = name_for(component_class)
 
@@ -115,6 +156,8 @@ module EcsRails
     end
 
     # Resets the registry. Used between tests and by the Railtie's `to_prepare`.
+    #
+    # @return [self]
     def clear!
       @declarations = {}
       self
@@ -125,11 +168,18 @@ module EcsRails
     # process-wide singleton and would otherwise wipe declarations that
     # host/app classes made at load time. `Declaration` is frozen and holds only
     # strings, so a shallow dup of the arrays is a safe, cheap copy.
+    #
+    # @return [Hash] an opaque snapshot to hand back to {#restore}
+    # @see #restore
     def snapshot
       @declarations.transform_values(&:dup)
     end
 
-    # Replaces the declarations with a previously taken #snapshot.
+    # Replaces the declarations with a previously taken {#snapshot}.
+    #
+    # @param snapshot [Hash] a value previously returned by {#snapshot}
+    # @return [self]
+    # @see #snapshot
     def restore(snapshot)
       @declarations = snapshot.transform_values(&:dup)
       self

data/lib/ecs_rails/relationships.rb

@@ -74,14 +74,29 @@ module EcsRails
   # (ADR-0011). The backing `*Relationship` class never appears in app code.
   module Relationships
     # One recorded relationship, held by NAME so it survives a Rails reload the
-    # same way the registry's Declaration does (RFC-0002): #backing_class and
-    # #target_class resolve via constantize on read, so a metadata entry taken
-    # before a reload still resolves to the post-reload constants.
+    # same way the registry's {EcsRails::Registry::Declaration} does (RFC-0002):
+    # {#backing_class} and {#target_class} resolve via `constantize` on read, so a
+    # metadata entry taken before a reload still resolves to the post-reload
+    # constants.
+    #
+    # @!attribute [rw] name
+    #   @return [Symbol] the relationship name, e.g. `:author`
+    # @!attribute [rw] backing_class_name
+    #   @return [String] the dynamically defined backing component,
+    #     e.g. `"Post::AuthorRelationship"`
+    # @!attribute [rw] foreign_key
+    #   @return [Symbol] the FK on the backing component, e.g. `:author_id`
+    # @!attribute [rw] target_class_name
+    #   @return [String] the entity pointed at, e.g. `"User"`
     RelationshipMeta = Struct.new(:name, :backing_class_name, :foreign_key, :target_class_name) do
+      # @return [Class<EcsRails::Component>] the backing component class
+      # @raise [NameError] if the constant no longer exists
       def backing_class
         backing_class_name.constantize
       end
 
+      # @return [Class<EcsRails::Entity>] the entity this relationship points at
+      # @raise [NameError] if the constant no longer exists
       def target_class
         target_class_name.constantize
       end
@@ -96,14 +111,40 @@ module EcsRails
 
     # Declares a cross-entity link named `name` at `target_class`.
     #
-    # `target_class` must be a concrete EcsRails::Entity; otherwise
-    # InvalidRelationship (a subclass of InvalidComponent — see errors.rb). `name`
-    # must not collide with an existing reader or delegated method on the entity;
-    # otherwise DelegationConflict, naming `name` (RFC-0012). Subclasses inherit
-    # the declaration exactly as they inherit `component` (the backing const lives
-    # on the declaring entity and resolves through ordinary constant lookup).
+    # Writes no relationship component file: it defines the backing component
+    # dynamically and declares it with {EcsRails::DSL#component}, so the whole
+    # stack — registry, lazy reader, delegation, querying, presence, preloading —
+    # applies for free.
+    #
+    # Subclasses inherit the declaration exactly as they inherit `component`.
+    #
+    # @example Declaring and using a relationship
+    #   class Post < ApplicationEntity
+    #     relates_to :author, User
+    #   end
+    #
+    #   post.author = user        # writer, delegated from the backing belongs_to
+    #   post.author               # => #<User>
+    #   post.author_relationship  # => the backing component row
     #
-    # Returns the Registry::Declaration for the backing component.
+    # @example Several relationships on one entity
+    #   class Membership < ApplicationEntity
+    #     relates_to :user, User
+    #     relates_to :team, Team
+    #     component Role
+    #   end
+    #
+    # @param name [Symbol, String] the relationship name. Becomes the delegated
+    #   accessor (`#author`, `#author=`), the `<name>_id` foreign key, and the
+    #   `<name>_relationship` backing reader.
+    # @param target_class [Class<EcsRails::Entity>] a concrete entity to point at
+    # @return [EcsRails::Registry::Declaration] the backing component's declaration
+    # @raise [EcsRails::InvalidRelationship] if `target_class` is not a concrete
+    #   entity — a component, an abstract entity, or a plain class
+    # @raise [EcsRails::DelegationConflict] if `name` collides with an existing
+    #   component reader, delegated method, or another relationship
+    # @see #with_related
+    # @see #includes_related
     def relates_to(name, target_class)
       name = name.to_sym
 
@@ -133,30 +174,49 @@ module EcsRails
       declaration
     end
 
-    # The recorded metadata for relationship `name` on this entity (RFC-0013),
-    # or nil if there is none. Walks the entity ancestry, so a subclass sees its
-    # parents' relationships — the same way #component_declarations does.
+    # The recorded metadata for relationship `name` on this entity (RFC-0013).
+    #
+    # Walks the entity ancestry, so a subclass sees its parents' relationships —
+    # the same way {EcsRails::DSL#component_declarations} does.
+    #
+    # @param name [Symbol, String] the relationship name
+    # @return [RelationshipMeta, nil] the metadata, or nil if undeclared
+    # @see #relationship_names
     def relationship_meta(name)
       relationship_declarations[name.to_sym]
     end
 
-    # The declared relationship names for this entity, ancestry included. Used
-    # in the InvalidRelationship message and handy for introspection.
+    # The declared relationship names for this entity, ancestry included.
+    #
+    # @example
+    #   Membership.relationship_names  # => [:user, :team]
+    #
+    # @return [Array<Symbol>] declared relationship names
+    # @see #relationship_meta
     def relationship_names
       relationship_declarations.keys
     end
 
     # Entities whose `name` relationship points at `target` (RFC-0013 / ADR-0014).
     #
-    # `target` may be an entity (its id is used) or a bare id. With no `target`,
-    # filters to entities that merely HAVE the relationship set (a backing row
-    # exists). Sugar for `with_component(backing, foreign_key => id)` — or
-    # `with_component(backing)` with no target — so it inherits that verb's
-    # entity-model scoping and correlated EXISTS (ADR-0011): no cross-entity leak.
+    # Sugar over {EcsRails::Querying#with_component}, so it inherits that verb's
+    # entity-model scoping and correlated EXISTS (ADR-0011) — no cross-entity
+    # leak. The backing `*Relationship` class never appears in app code.
+    #
+    # @example Posts by a given author
+    #   Post.with_related(:author, ada)
+    #   Post.with_related(:author, ada.id)   # a bare id works too
     #
-    # Returns a chainable ActiveRecord::Relation. Available on the class and on a
-    # relation, like the component verbs, because it builds on them (they run on
-    # `all`, the current default-scoped relation).
+    # @example Posts that have *any* author set
+    #   Post.with_related(:author)
+    #
+    # @param name [Symbol, String] a declared relationship name
+    # @param target [EcsRails::Entity, Integer, String] the target entity or its
+    #   id. Omit to match entities that merely have the relationship set.
+    # @return [ActiveRecord::Relation] chainable, entity-model scoped
+    # @raise [EcsRails::InvalidRelationship] if `name` is not declared
+    # @see #without_related
+    # @see #includes_related
     def with_related(name, target = ANY_TARGET)
       meta = ecs_resolve_relationship!(name)
 
@@ -166,8 +226,18 @@ module EcsRails
       with_component(meta.backing_class, meta.foreign_key => id)
     end
 
-    # Entities with NO backing row for `name` (RFC-0013). Sugar for
-    # `without_component(backing)`; inherits its NULL-safe NOT EXISTS (ADR-0011).
+    # Entities with NO backing row for `name` (RFC-0013).
+    #
+    # Sugar over {EcsRails::Querying#without_component}; inherits its NULL-safe
+    # `NOT EXISTS` (ADR-0011).
+    #
+    # @example Orphaned posts
+    #   Post.without_related(:author)
+    #
+    # @param name [Symbol, String] a declared relationship name
+    # @return [ActiveRecord::Relation] chainable, entity-model scoped
+    # @raise [EcsRails::InvalidRelationship] if `name` is not declared
+    # @see #with_related
     def without_related(name)
       without_component(ecs_resolve_relationship!(name).backing_class)
     end
@@ -175,13 +245,17 @@ module EcsRails
     # Preloads each named relationship's backing component AND its target entity
     # — one hop — so `entity.author` costs no extra query (RFC-0013 / ADR-0014).
     #
-    # For `:author` that is `preload(author_relationship: :author)`: the backing
-    # reader is `<name>_relationship` (the backing's model_name.singular, pinned
-    # by ADR-0013) and the target association on the backing is the `<name>`
-    # belongs_to. Does NOT preload the target's own components (ADR-0014 non-goal).
+    # For `:author` that is `preload(author_relationship: :author)`. Does **not**
+    # preload the target's own components (ADR-0014 non-goal) — chain
+    # {EcsRails::Preloading#includes_components} on the target for that.
+    #
+    # @example
+    #   Post.published.includes_related(:author).each { |p| p.author.name }
     #
-    # Chainable; returns a relation. Built from `all`, like Preloading, so it
-    # keeps any prior scope and the entity-model default scope.
+    # @param names [Array<Symbol, String>] declared relationship names
+    # @return [ActiveRecord::Relation] chainable, entity-model scoped
+    # @raise [EcsRails::InvalidRelationship] if any name is not declared
+    # @see #with_related
     def includes_related(*names)
       preloads = names.map do |name|
         meta = ecs_resolve_relationship!(name)

data/lib/ecs_rails/version.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
 module EcsRails
-  VERSION = "0.2.1"
+  # The gem version. Published on RubyGems as `ecs_on_rails`.
+  #
+  # @return [String] the semantic version, e.g. `"0.2.2"`
+  VERSION = "0.2.2"
 end

data/lib/ecs_rails.rb

@@ -19,10 +19,44 @@ require "ecs_rails/component"
 
 # ECS Rails — an Entity-Component-System reimagining of ActiveRecord.
 #
-# See docs/architecture.md for the invariants this library guarantees.
+# Replaces one-table-per-model with one-table-per-component. An {EcsRails::Entity}
+# is a lightweight identity row; all state and behaviour live in small, reusable
+# {EcsRails::Component}s composed onto it.
+#
+# The gem is published as **`ecs_on_rails`**, but the require path and module are
+# `ecs_rails` / `EcsRails` — see the README for why.
+#
+# @example Composing an entity from components
+#   class User < ApplicationEntity
+#     component Name
+#     component Email
+#     component Moderator        # a marker: no data, presence is the meaning
+#   end
+#
+#   user = User.create!          # one row in `entities`, no component rows
+#   user.email                   # => #<Email> — virtual, not persisted
+#   user.email.address = "a@b.com"
+#   user.save!                   # now `emails` gets a row
+#
+# @see EcsRails::Entity     Identity, and the class-level DSL entry point
+# @see EcsRails::Component  The ActiveRecord model a component is
+# @see EcsRails::DSL        `component` — composition
+# @see EcsRails::Relationships `relates_to` — cross-entity links
+# @see EcsRails::Querying   `with_component` / `without_component`
+# @see EcsRails::Preloading `includes_components`
+# @see EcsRails::Presence::Entity `add` / `has?` / `remove`
+# @see https://github.com/kranzky/ecs_rails/blob/main/docs/architecture.md
+#   architecture.md — the invariants this library guarantees
 module EcsRails
   class << self
-    # The process-wide component registry. See RFC-0002.
+    # The process-wide component registry, populated by the {EcsRails::DSL#component}
+    # DSL at class-load time.
+    #
+    # Keyed by class *name* rather than class object, so it survives Rails
+    # reloading (RFC-0002).
+    #
+    # @return [EcsRails::Registry] the singleton registry
+    # @see EcsRails::Registry
     def registry
       @registry ||= Registry.new
     end
@@ -30,14 +64,21 @@ module EcsRails
     # The process-wide generator configuration (ADR-0010). Layout only — the
     # runtime does not consult it; the generators and the initializer they emit
     # do.
+    #
+    # @return [EcsRails::Config] the singleton configuration
+    # @see #configure
     def config
       @config ||= Config.new
     end
 
     # Yields the config for block-style setup, as a host app's
-    # config/initializers/ecs_rails.rb does:
+    # `config/initializers/ecs_rails.rb` does.
     #
+    # @example Restoring the pre-ADR-0010 single-directory layout
     #   EcsRails.configure { |config| config.entities_path = "app/models" }
+    #
+    # @yieldparam config [EcsRails::Config] the process-wide configuration
+    # @return [EcsRails::Config] the configuration, after the block has run
     def configure
       yield config
     end

data/lib/generators/ecs_rails/component/component_generator.rb

@@ -40,6 +40,11 @@ module EcsRails
 
       desc "Creates a component: its migration, its model, and its spec."
 
+      # Emits the component's table migration.
+      #
+      # A Thor task: invoked as a generator step, not called directly.
+      #
+      # @return [void]
       def create_migration_file
         migration_template(
           "migration.rb.tt",

data/lib/generators/ecs_rails/install/install_generator.rb

@@ -17,6 +17,11 @@ require "rails/generators/active_record/migration"
 require "ecs_rails"
 
 module EcsRails
+  # The Rails generators (RFC-0008): `ecs_rails:install`, `ecs_rails:component`
+  # and `ecs_rails:relationship`.
+  #
+  # They read {EcsRails.config} to place their files (ADR-0010). The gem runtime
+  # never consults that config — only these do.
   module Generators
     # `rails g ecs_rails:install`
     #
@@ -34,6 +39,11 @@ module EcsRails
       desc "Creates the entities migration and the ApplicationEntity / " \
            "ApplicationComponent base classes."
 
+      # Emits the `entities` table migration.
+      #
+      # A Thor task: invoked as a generator step, not called directly.
+      #
+      # @return [void]
       def create_migration_file
         migration_template(
           "migration.rb.tt",

data/lib/generators/ecs_rails/relationship/relationship_generator.rb

@@ -43,6 +43,11 @@ module EcsRails
 
       desc "Creates the migration for a relationship's backing table (no model)."
 
+      # Emits the backing relationship table migration.
+      #
+      # A Thor task: invoked as a generator step, not called directly.
+      #
+      # @return [void]
       def create_migration_file
         parse_relationship!
         migration_template(

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ecs_on_rails
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Jason Hutchens
@@ -80,6 +80,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
@@ -114,9 +115,10 @@ homepage: https://github.com/kranzky/ecs_rails
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/kranzky/ecs_rails
-  changelog_uri: https://github.com/kranzky/ecs_rails/blob/main/CHANGELOG.md
+  source_code_uri: https://github.com/kranzky/ecs_rails/tree/main/gem
+  changelog_uri: https://github.com/kranzky/ecs_rails/blob/main/gem/CHANGELOG.md
   bug_tracker_uri: https://github.com/kranzky/ecs_rails/issues
+  documentation_uri: https://rubydoc.info/gems/ecs_on_rails
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: