roast-ai 0.4.10 → 0.5.0

data/internal/documentation/doc-comments-internal.md

@@ -0,0 +1,342 @@
+# Developer-Facing Documentation Guidelines
+
+This document provides guidelines for writing developer-facing documentation comments in Roast. Developer-facing documentation appears in internal implementation code that Roast core contributors work with directly.
+
+## Where This Applies
+
+Developer-facing documentation can be more concise since developers have the code right in front of them.
+
+**Applies to:**
+
+- Cog classes themselves (e.g., `Agent`, `Chat`, `Cmd`)
+- All `Params` classes for system cogs (e.g., `SystemCog::Params`)
+- Standard cog methods like `execute`, `initialize`
+- Internal helper methods and utilities
+- Private methods (if documented at all)
+
+## Documentation Requirements
+
+Developer-facing documentation should be concise and focused:
+
+- Focus on usage, interface guarantees, and expectations
+- Do **NOT** describe implementation details
+- Do **NOT** include `#### See Also` sections (code is right there)
+- Keep it concise - one-line summary is often sufficient
+- Only add additional context when interface contracts aren't obvious from the method signature
+
+## Basic Format
+
+Documentation comments follow this minimal structure:
+
+```ruby
+# [One-line summary of what the method does]
+#
+#: (ParamType) -> ReturnType  # Type signatures are enforced by Sorbet/RuboCop
+def method_name(param)
+  # implementation
+end
+```
+
+For methods where the interface contract is clear from the signature, a one-line description is sufficient:
+
+```ruby
+# Execute the agent with the given input and return the output
+#
+#: (Input) -> Output
+def execute(input)
+  # implementation
+end
+```
+
+## Writing Clear Descriptions
+
+### One-Line Descriptions
+
+Start with a clear, action-oriented description in imperative mood. The first line should **not** end with a period:
+
+```ruby
+# Execute the chat completion with the given input and return the output
+#
+#: (Input) -> Output
+def execute(input)
+  # implementation
+end
+```
+
+**Good patterns:**
+
+- "Execute..."
+- "Initialize..."
+- "Get..."
+- "Create..."
+
+**Avoid:**
+
+- Passive voice: "The input is executed..."
+- Redundant phrases: "This method executes..."
+- Implementation details: "Calls the provider's invoke method..."
+- Ending with a period
+
+### When to Add Additional Context
+
+Only add additional lines when the interface contract isn't obvious from the method signature and one-line description:
+
+```ruby
+# Get the RubyLLM context configured for this chat cog
+#
+# Returns a cached context object that is lazily initialized on first access
+# and reused for subsequent calls.
+#
+#: () -> RubyLLM::Context
+def ruby_llm_context
+  @ruby_llm_context ||= RubyLLM.context do |context|
+    # configuration
+  end
+end
+```
+
+In this example, the additional context about caching and lazy initialization is valuable because it's not obvious from the signature.
+
+## Class Documentation
+
+Document cog classes with a brief description of their purpose:
+
+```ruby
+# Agent cog for executing AI agent workflows
+#
+# Enables interaction with AI agent providers to perform complex reasoning
+# and tool-using tasks. Unlike the simpler chat cog, agents can use tools,
+# maintain session state, and track detailed execution statistics.
+class Agent < Cog
+  # ...
+end
+```
+
+**Key points:**
+
+- Describe the cog's purpose concisely
+- Mention key capabilities that distinguish it from other cogs
+- Do NOT include `#### See Also` sections
+- Do NOT describe implementation details
+
+## Error Class Documentation
+
+Document error classes with brief descriptions of when they're raised:
+
+```ruby
+# Parent class for all agent cog errors
+class AgentCogError < Roast::Error; end
+
+# Raised when an unknown or unsupported provider is specified
+class UnknownProviderError < AgentCogError; end
+
+# Raised when a required provider is not configured
+class MissingProviderError < AgentCogError; end
+```
+
+**Key points:**
+
+- One line is sufficient
+- Describe when the error is raised
+- No need for extensive context
+
+## Attribute Documentation
+
+Document public attributes with brief descriptions:
+
+```ruby
+# The configuration object for this agent cog instance
+#
+#: Agent::Config
+attr_reader :config
+```
+
+**Key points:**
+
+- One line is usually sufficient
+- Do NOT include `#### See Also` sections
+- Type signature provides most of the needed information
+
+## Standard Method Patterns
+
+### Execute Methods
+
+All cog `execute` methods should have minimal documentation:
+
+```ruby
+# Execute the agent with the given input and return the output
+#
+#: (Input) -> Output
+def execute(input)
+  # implementation
+end
+```
+
+**Do NOT document:**
+- What happens internally (provider invocation, display logic, etc.)
+- Configuration options (those are documented in Config class)
+- Implementation details
+
+### Initialize Methods
+
+Rarely need documentation beyond type signature since constructor behavior is standard:
+
+```ruby
+#: (String response) -> void
+def initialize(response)
+  super()
+  @response = response
+end
+```
+
+Only add a comment if the initialization does something non-obvious.
+
+## What Not to Document
+
+Avoid documenting:
+
+- **Implementation details** - How the method accomplishes its goal
+- **Obvious information** - What's clear from the method name and signature
+- **Private methods** - Generally don't need documentation comments
+- **Internal mechanics** - Instance variable usage, caching strategies, etc.
+- **Cross-references** - Code is right there, no need for `#### See Also`
+
+**Bad example:**
+
+```ruby
+# Execute the agent by calling the provider's invoke method with the input,
+# then checking the config to see if we should print the prompt, response,
+# and stats to the console, and finally returning the output object
+#
+#: (Input) -> Output
+def execute(input)
+  # implementation
+end
+```
+
+This is too detailed and describes implementation rather than interface.
+
+**Good example:**
+
+```ruby
+# Execute the agent with the given input and return the output
+#
+#: (Input) -> Output
+def execute(input)
+  # implementation
+end
+```
+
+## Markdown Formatting
+
+Use minimal markdown formatting in developer-facing documentation:
+
+### Inline Code
+
+Use backticks for:
+
+- Method names: `` `execute` ``
+- Values: `` `true` ``, `` `:claude` ``
+- Cog names: `` `call` ``, `` `map` ``, `` `agent` `` (they appear as methods from a user's perspective)
+- Class names: Use **fully qualified names** (e.g., `` `Roast::DSL::Cogs::Agent::Input` ``)
+
+**Important:** Always use fully qualified class/module names in documentation to avoid ambiguity.
+Due to significant name overlap in the system (e.g., multiple `Input`, `Output`, `Config` classes),
+shortened names can be confusing. Use the complete module path.
+
+**Note:** "System" cogs (like `call`, `map`, `repeat`) are an internal implementation detail that inherit from `SystemCog` rather than `Cog`. This distinction is irrelevant in documentation - all cogs should be presented consistently regardless of their base class.
+
+```ruby
+# Get a RubyLLM context configured for this chat cog
+#
+#: () -> RubyLLM::Context
+def ruby_llm_context
+  # implementation
+end
+```
+
+**Examples:**
+- ✅ Good: `` `Roast::DSL::SystemCogs::Call::Output` ``
+- ❌ Bad: `` `Call::Output` `` (ambiguous)
+
+### Bold Emphasis
+
+Use sparingly, only for critical negations if needed:
+
+```ruby
+# Execute the agent but do __not__ display progress to the console
+#
+#: (Input) -> Output
+def execute_silently(input)
+  # implementation
+end
+```
+
+### No Subsections
+
+Do **NOT** use subsections like `#### See Also` in developer-facing documentation. Developers can see related methods in the code.
+
+## Review Checklist
+
+Before finalizing developer-facing documentation, verify:
+
+- [ ] One-line description is clear and action-oriented
+- [ ] First line does not end with a period
+- [ ] Focus is on interface contract (what it does), not implementation (how it does it)
+- [ ] No `#### See Also` sections are included (code is right there)
+- [ ] Documentation is concise - additional context only when interface isn't obvious
+- [ ] No implementation details are exposed
+- [ ] Error conditions are mentioned only if not obvious from signature
+- [ ] Markdown formatting is correct
+
+## Examples
+
+### Minimal Documentation (Preferred)
+
+```ruby
+# Execute the chat completion with the given input and return the output
+#
+#: (Input) -> Output
+def execute(input)
+  # implementation
+end
+```
+
+### With Necessary Context
+
+```ruby
+# Get the RubyLLM context configured for this chat cog
+#
+# Returns a cached context object that is lazily initialized on first access
+# and reused for subsequent calls.
+#
+#: () -> RubyLLM::Context
+def ruby_llm_context
+  @ruby_llm_context ||= RubyLLM.context do |context|
+    context.openai_api_key = config.valid_api_key!
+    context.openai_api_base = config.valid_base_url
+  end
+end
+```
+
+### Class Documentation
+
+```ruby
+# Chat cog for executing simple LLM chat completions
+#
+# Provides a straightforward interface for single-turn interactions with
+# language models without tool use or conversation state management.
+class Chat < Cog
+  # ...
+end
+```
+
+### Error Class Documentation
+
+```ruby
+# Parent class for all agent cog errors
+class AgentCogError < Roast::Error; end
+
+# Raised when an unknown or unsupported provider is specified
+class UnknownProviderError < AgentCogError; end
+```

data/internal/documentation/doc-comments.md

@@ -0,0 +1,211 @@
+# Documentation Comment Guidelines
+
+This document establishes standards for writing documentation comments in the Roast DSL codebase. Well-documented interfaces are critical for both internal development and community contributions.
+
+## Purpose and Audience
+
+Documentation comments should serve developers who will use these interfaces, not just those who will maintain them.
+Write for:
+
+- Roast core contributors
+- Community contributors
+- Users extending Roast with custom cogs
+
+## Architectural Context
+
+Before writing documentation, consult [architectural-notes.md](./architectural-notes.md) for key architectural decisions and distinctions that should guide how we talk about cogs and their functionality. This file captures important context such as:
+
+- The distinction between `agent` and `chat` cogs
+- Design decisions that affect how we describe cog capabilities
+- Guidelines for avoiding misleading characterizations
+
+Always ensure your documentation aligns with the architectural guidance in that file.
+
+## Two Types of Documentation
+
+Roast has two distinct types of documentation with different thoroughness requirements. Understanding which type you're writing is essential to creating appropriate documentation.
+
+### User-Facing Documentation (External)
+
+**For workflows users interact with directly.**
+
+User-facing documentation appears in interfaces that Roast users write in their workflow files. These require the **most thorough documentation** and should **NOT assume knowledge** of how Roast works internally.
+
+**Where user-facing documentation appears:**
+
+- All `Config` classes for cogs (e.g., `Agent::Config`, `Chat::Config`, `Cmd::Config`)
+- All `Input` classes for cogs (e.g., `Agent::Input`, `Chat::Input`)
+- All `Output` classes for cogs (e.g., `Agent::Output`, `Chat::Output`)
+- `.rbi` shims in `sorbet/rbi/shims/lib/roast/` - **These are critically important!**
+
+#### Why .rbi Shims Are Critical
+
+The `.rbi` shim files contain some of the most important user-facing documentation in Roast. These files define the methods that users call when writing workflows, and the documentation in these files is what users see in their IDE when they invoke these methods.
+
+**Key .rbi shim files and their purposes:**
+
+- **`execution_context.rbi`**: Documents methods users call when defining cogs in `execute` blocks (e.g., `agent!`, `chat!`, `cmd!`, `call!`, `map!`, `repeat!`)
+- **`config_context.rbi`**: Documents methods users call when configuring cogs in `config` blocks (e.g., `agent { ... }`, `chat { ... }`, `cmd { ... }`)
+  - **This is the primary way users discover what configuration options are available**
+  - Must document ALL user-facing configuration methods on each cog's Config object (excluding internal methods like `valid_*`)
+  - Configuration options should be grouped by purpose using `####` subsection headers (e.g., "Configure the LLM provider", "Configure the working directory")
+- **`cog_input_context.rbi`**: Documents methods users call in cog input blocks to access outputs from other cogs (e.g., `from`, `collect`, `reduce`)
+
+These files provide the primary interface between users and Roast. The documentation must be exceptional because it's what users see at the exact moment they need help.
+
+**Requirements:**
+
+- Be extremely thorough
+- Include comprehensive `#### See Also` sections with cross-references
+- Explain default behaviors and edge cases
+- Document error conditions
+- Provide context about what the method does and why you'd use it
+- Don't assume the reader understands Roast internals
+
+**📖 See [doc-comments-external.md](./doc-comments-external.md) for complete user-facing documentation guidelines.**
+
+**Example:**
+
+```ruby
+# Configure the cog to use a specified provider when invoking an agent
+#
+# The provider is the source of the agent tool itself.
+# If no provider is specified, Anthropic Claude Code (`:claude`) will be used as the default provider.
+#
+# A provider must be properly installed on your system in order for Roast to be able to use it.
+#
+# #### See Also
+# - `use_default_provider!`
+#
+#: (Symbol) -> void
+def provider(provider)
+  @values[:provider] = provider
+end
+```
+
+### Developer-Facing Documentation (Internal)
+
+**For Roast core implementation code.**
+
+Developer-facing documentation appears in internal implementation code that Roast core contributors work with directly. These can be **more concise** since developers have the code right in front of them.
+
+**Where developer-facing documentation appears:**
+
+- Cog classes themselves (e.g., `Agent`, `Chat`, `Cmd`)
+- All `Params` classes for system cogs (e.g., `SystemCog::Params`)
+- Standard cog methods like `execute`, `initialize`
+- Internal helper methods and utilities
+- Private methods (if documented at all)
+
+**Requirements:**
+
+- Focus on usage, interface guarantees, and expectations
+- Do **NOT** describe implementation details
+- Do **NOT** include `#### See Also` sections (code is right there)
+- Keep it concise - one-line summary is often sufficient
+- Only add additional context when interface contracts aren't obvious from the method signature
+
+**📖 See [doc-comments-internal.md](./doc-comments-internal.md) for complete developer-facing documentation guidelines.**
+
+**Example:**
+
+```ruby
+# Execute the agent with the given input and return the output
+#
+#: (Input) -> Output
+def execute(input)
+  # implementation
+end
+```
+
+Notice: no `#### See Also`, no detailed explanation of what happens internally, just the interface contract.
+
+## Quick Reference
+
+### When to Use External Guidelines
+
+Use [doc-comments-external.md](./doc-comments-external.md) when documenting:
+
+- ✅ `Config` class methods (all configuration setters, getters, predicates)
+- ✅ `Input` class methods and attributes
+- ✅ `Output` class methods and attributes
+- ✅ `.rbi` shim definitions (especially `execution_context.rbi`, `config_context.rbi`, `cog_input_context.rbi`)
+
+### When to Use Internal Guidelines
+
+Use [doc-comments-internal.md](./doc-comments-internal.md) when documenting:
+
+- ✅ Cog class definitions (e.g., `class Agent < Cog`)
+- ✅ `Params` class methods and attributes (e.g., `SystemCog::Params`)
+- ✅ `execute` methods on cog classes
+- ✅ `initialize` methods on cog classes
+- ✅ Private helper methods
+- ✅ Internal utilities and support classes
+
+## General Principles
+
+Regardless of which type of documentation you're writing, follow these universal principles:
+
+### One-Line Descriptions
+
+- Start with a clear, action-oriented description in imperative mood
+- The first line should **NOT** end with a period
+- Use active voice, not passive
+- Be specific and precise
+
+### Multi-Line Descriptions
+
+- Separate paragraphs with blank comment lines
+- All lines after the first line should be complete sentences ending with a period
+- Add context and details after the one-line summary
+
+### Markdown Formatting
+
+- Use double underscores (`__word__`) for bold emphasis on critical negating words
+- Use backticks (`` `code` ``) for method names, values, symbols, class names, and cog names
+- **Cog names should always be stylized with backticks** (e.g., `` `call` ``, `` `map` ``, `` `agent` ``) since they appear as methods from a user's perspective
+- **Always use fully qualified class/module names** (e.g., `Roast::DSL::SystemCogs::Call::Output`, not `Call::Output`) to avoid ambiguity
+- Use `####` for subsection headers in user-facing documentation only
+- Use `-` for bullet lists
+
+**Note:** "System" cogs are an internal implementation detail. From the user's perspective, all cogs provided by core Roast should be presented the same way. Never distinguish between "system cogs" and "regular cogs" in user-facing documentation.
+
+**Note:** `ExecutionManager` is an internal implementation detail. Never mention execution managers in user-facing documentation (Config, Input, Output classes). Focus on what the user can do with the output, not on the internal mechanisms.
+
+### Type Signatures
+
+- Always include inline RBS type signatures using `#:` comments
+- Type signatures are enforced by Sorbet and RuboCop
+- Place type signatures immediately before the method definition
+
+### What Not to Document
+
+- **Implementation details** - Focus on behavior, not how it's achieved
+- **Obvious information** - Don't state what's clear from the method name
+- **Internal mechanics** - How instance variables work, caching strategies, etc.
+
+## Getting Started
+
+1. **Identify which type of documentation you need:**
+   - Are you documenting a Config/Input/Output class or .rbi shim? → Use [external guidelines](./doc-comments-external.md)
+   - Are you documenting a Params class, cog class, or internal method? → Use [internal guidelines](./doc-comments-internal.md)
+
+2. **Read the appropriate guide:**
+   - [doc-comments-external.md](./doc-comments-external.md) - Comprehensive user-facing documentation
+   - [doc-comments-internal.md](./doc-comments-internal.md) - Concise developer-facing documentation
+
+3. **Follow the examples and patterns** in your chosen guide
+
+4. **Review your documentation** using the checklist at the end of your guide
+
+## Questions?
+
+If you're unsure which type of documentation applies:
+
+- **Ask yourself:** "Will a Roast user call this method directly in their workflow file or see this documentation in their IDE?"
+  - If YES → Use external (user-facing) guidelines
+  - If NO → Use internal (developer-facing) guidelines
+
+- **.rbi shim files are always user-facing** - If you're documenting anything in `sorbet/rbi/shims/lib/roast/`, use external guidelines
+
+- **Still unsure?** Default to external guidelines - it's better to be thorough than too brief.