Add YARD documentation to all public methods

[kxzk]

TL;DR

Add comprehensive YARD documentation (@return, @param, @raise, @example) to every public method, attribute, and constant across the SDK.

Why

Running yard doc currently produces incomplete output because most public APIs lack annotations. This makes it harder for consumers to discover the SDK surface area. Adding YARD tags enables full API reference generation and improves IDE autocompletion / hover docs.

Checklist

• Has label
• Has linked issue
• Tests added for new behavior
• Docs updated (if user-facing)

No new tests needed — these are documentation-only changes with zero behavioral impact. All existing tests pass.

[greptile-apps]

Greptile Overview

Greptile Summary

This PR adds comprehensive YARD annotations across the public SDK surface (attrs, constants, and methods), including @param, @return, @raise, and usage @examples. These changes improve generated yard doc output and IDE hover/autocomplete without intended runtime behavior changes.

One issue to fix before merge: in lib/langfuse/cache_warmer.rb, the docs now claim versions/labels params are non-nil Hashes, but the code and surrounding prose still treat them as optional and accept nil. This will generate incorrect API docs for callers.

Confidence Score: 4/5

• This PR is low-risk and close to merge, with one documentation correctness issue to fix.
• Changes are overwhelmingly comment/YARD additions with no detected runtime modifications. The main concern is a concrete mismatch between parameter nilability in CacheWarmer YARD annotations vs. actual optional behavior, which will produce incorrect public docs until corrected.
• lib/langfuse/cache_warmer.rb

Important Files Changed

Filename	Overview
lib/langfuse.rb	Documentation-only additions: class/module docs and extra YARD tags (e.g., @raise/@param) for public APIs; no behavioral changes observed.
lib/langfuse/api_client.rb	Adds YARD @return/@raise/@example tags and splits attr_reader docs; no functional code changes detected.
lib/langfuse/cache_warmer.rb	YARD param type annotations changed; versions/labels were documented as non-nil Hash but remain optional (nil accepted), which makes docs incorrect.
lib/langfuse/chat_prompt_client.rb	Splits prompt client attr_readers into individually documented accessors; no runtime changes.
lib/langfuse/client.rb	Adds YARD @return/@example tags and documents attr_readers; no behavior changes found.
lib/langfuse/config.rb	Adds YARD @return annotations for constants and initializer; constants/behavior unchanged.
lib/langfuse/dataset_client.rb	Introduces class-level YARD docs and documents accessors; no logic changes.
lib/langfuse/dataset_item_client.rb	Adds class-level YARD docs and accessor return types; no functional changes.
lib/langfuse/observations.rb	Adds/clarifies YARD docs for observation classes and setters; runtime logic untouched.
lib/langfuse/otel_setup.rb	Adds YARD return type for tracer_provider reader; no code changes.
lib/langfuse/prompt_cache.rb	Documents cache attr_readers with YARD @return; no functional diffs.
lib/langfuse/propagation.rb	Adds missing YARD @raise tags for argument validation; implementation unchanged.
lib/langfuse/rails_cache_adapter.rb	Documents adapter attr_readers individually with YARD; no behavior changes.
lib/langfuse/score_client.rb	Adds YARD docs for readers; no runtime changes.
lib/langfuse/text_prompt_client.rb	Splits and documents prompt client attr_readers; no code behavior changes.

Sequence Diagram

sequenceDiagram
    autonumber
    participant User
    participant Langfuse as Langfuse (module)
    participant Client
    participant ApiClient
    participant CacheWarmer
    participant PromptCache

    User->>Langfuse: configure { ... }
    User->>Langfuse: client
    Langfuse-->>User: Client

    Note over User,Client: Prompt fetching w/ optional caching
    User->>Client: get_prompt(name, version/label)
    Client->>ApiClient: get_prompt(...)
    alt cache configured
        ApiClient->>PromptCache: fetch(key) / store(key, value)
        PromptCache-->>ApiClient: cached prompt or miss
    end
    ApiClient-->>Client: prompt data
    Client-->>User: TextPromptClient / ChatPromptClient

    Note over User,CacheWarmer: Cache warming flow
    User->>CacheWarmer: warm_prompts(prompt_names, versions?, labels?)
    CacheWarmer->>Client: get_prompt(...) (per prompt)
    Client->>ApiClient: get_prompt(...)
    ApiClient->>PromptCache: store(...)
    PromptCache-->>ApiClient: ok
    ApiClient-->>Client: prompt data
    Client-->>CacheWarmer: prompt client
    CacheWarmer-->>User: { success: [...], failed: [...] }

Loading

[greptile-apps]

_{15 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Additional Comments (1)

lib/langfuse/cache_warmer.rb
Incorrect nilability docs

In CacheWarmer#warm_prompts/warm_all_prompts/warm_prompts!, the YARD docs were changed from versions [Hash<String, Integer>, nil] / labels [Hash<String, String>, nil] to non-nil types, but the methods still accept nil (and the docs above still describe them as “Optional”). This makes generated docs misleading and will confuse callers relying on nil defaults. Please restore the , nil in these param types (or update the method signatures to truly require hashes).

[Copilot]

Pull request overview

Adds/extends YARD annotations across the Langfuse Ruby SDK so yard doc generates a more complete public API reference and IDEs can surface richer hover/autocomplete information.

Changes:

• Documented public readers (attr_reader) with @return types across multiple clients/adapters.
• Added/expanded method docs with @raise, @return [void], and @example where applicable.
• Added class/module-level documentation for dataset wrappers and error classes.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
lib/langfuse/text_prompt_client.rb	Adds YARD @return docs for prompt metadata readers.
lib/langfuse/chat_prompt_client.rb	Adds YARD @return docs for prompt metadata readers.
lib/langfuse/score_client.rb	Adds YARD @return docs for core dependency readers.
lib/langfuse/rails_cache_adapter.rb	Adds YARD @return docs for cache configuration/state readers.
lib/langfuse/prompt_cache.rb	Adds YARD @return docs for cache configuration readers.
lib/langfuse/otel_setup.rb	Documents singleton tracer_provider reader return type.
lib/langfuse/propagation.rb	Adds missing @raise tags to match behavior.
lib/langfuse/observations.rb	Adds YARD return/type docs for observation readers and setters.
lib/langfuse/dataset_client.rb	Adds wrapper class docs + typed accessors + items return type.
lib/langfuse/dataset_item_client.rb	Adds wrapper class docs + typed accessors + status helpers docs.
lib/langfuse/config.rb	Documents constants/defaults and initialize return.
lib/langfuse/client.rb	Documents core readers and adds examples for dataset APIs.
lib/langfuse/cache_warmer.rb	Documents client reader and updates param typing docs.
lib/langfuse/api_client.rb	Documents core readers and adds dataset API examples + shutdown docs.
lib/langfuse.rb	Documents error classes and adds/extends method parameter/raise docs.

---

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

[Copilot]

ApiClient#cache can also be a RailsCacheAdapter (e.g., when Config#cache_backend is :rails and Client#create_cache builds RailsCacheAdapter.new). The YARD type annotations for the cache reader and the initialize @param cache currently only mention PromptCache; please expand them to include RailsCacheAdapter (or a shared cache interface type) so the generated docs match actual usage.