Add YARD documentation and fill README Usage section

[tagliala]

• Add YARD documentation to all lib files (hawk.rb, model.rb, http.rb, etc.)
• Document all public methods with @param, @return, @raise, @example tags
• Fill README Usage section with examples for:
  • Defining models with schema
  • Finding records (find, find!, first, first!, all)
  • Querying (where, limit, offset, order, includes)
  • Defining and using scopes
  • Associations (has_many, has_one, belongs_to, polymorphic)
  • Caching configuration
  • Error handling
  • Persisting records with ActiveModel
  • Instrumentation

Closes #7

[Copilot]

Pull request overview

This PR focuses on improving developer-facing documentation by adding YARD docstrings across Hawk’s public API surface and by filling out the README “Usage” section with practical examples, addressing Issue #7.

Changes:

• Expanded README.md with end-to-end usage examples (models, querying, scopes, associations, caching, errors, persistence, instrumentation).
• Added/expanded YARD documentation throughout lib/ for model/query/HTTP/error modules and classes.
• Updated Development section guidance for building a local gem artifact.

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
README.md	Adds detailed usage examples and updates installation/development guidance.
lib/hawk/version.rb	Adds module/version documentation.
lib/hawk/model/scoping.rb	Documents scope definition and usage.
lib/hawk/model/schema/dsl.rb	Documents schema DSL; highlights DSL method_missing behavior.
lib/hawk/model/schema.rb	Documents schema definition/casting and caster internals.
lib/hawk/model/querying.rb	Documents query-building/chaining API.
lib/hawk/model/proxy.rb	Documents proxy chaining/enumeration behavior.
lib/hawk/model/pagination.rb	Documents pagination helpers and Kaminari integration.
lib/hawk/model/lookup.rb	Documents model class resolution behavior.
lib/hawk/model/finder.rb	Documents find/all/count and instantiation behavior.
lib/hawk/model/connection.rb	Documents connection configuration and delegated HTTP helpers.
lib/hawk/model/configurator.rb	Documents configuration propagation to subclasses.
lib/hawk/model/collection.rb	Documents collection metadata and pagination-related behavior.
lib/hawk/model/base.rb	Documents the primary model base class and included capabilities.
lib/hawk/model/association.rb	Documents association macros and preloading behavior.
lib/hawk/model/active.rb	Documents ActiveModel integration, dirty tracking, persistence.
lib/hawk/model.rb	Adds Model namespace/module documentation.
lib/hawk/linker.rb	Documents resource_accessor behavior (mono/poly).
lib/hawk/http/instrumentation.rb	Documents instrumentation options and logging behavior.
lib/hawk/http/caching.rb	Documents Memcached caching configuration and behavior.
lib/hawk/http.rb	Documents HTTP client API, options, and error handling.
lib/hawk/error.rb	Documents error hierarchy and usage patterns.

Comments suppressed due to low confidence (2)

lib/hawk/model/association.rb:160

• The example block parameters in the preload_association docs don't match the actual yield signature (|scope, attributes|) and reference variables that won't exist. This makes the example copy/paste break.

        # @example Custom preloading
        #   class Foo < Hawk::Model::Base
        #     has_many :bars
        #
        #     preload_association do |attributes, name, type, options|

lib/hawk/model/schema.rb:305

• Caster#to_s includes an extra closing parenthesis in the string representation (...:#{line})>), which looks like a typo in debug output.

        def to_s
          src, line = @code.source_location
          "#<Cast to #{type} using #{File.basename(src)}:#{line})>"
        end

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.