agy-superpowers 5.1.4 → 5.1.6

package/template/agent/skills/rust-developer/references/rust-rules/doc-intra-links.md

@@ -0,0 +1,138 @@
+# doc-intra-links
+
+> Use intra-doc links to reference types and items
+
+## Why It Matters
+
+Intra-doc links (`[TypeName]`, `[method](Self::method)`) create clickable references in generated documentation. They're verified at doc-build time, catching broken links early. Unlike URL links, they automatically update when items are renamed or moved.
+
+## Bad
+
+```rust
+/// Returns the length of the buffer.
+/// 
+/// See also `capacity()` for the allocated size, and the
+/// `Buffer` struct for more details.
+pub fn len(&self) -> usize {
+    self.data.len()
+}
+
+/// Parses the input using std::str::FromStr trait.
+/// Check the Error enum for possible failures.
+pub fn parse<T: FromStr>(input: &str) -> Result<T, Error> {
+    // ...
+}
+```
+
+## Good
+
+```rust
+/// Returns the length of the buffer.
+/// 
+/// See also [`capacity()`](Self::capacity) for the allocated size, and
+/// [`Buffer`] for more details.
+pub fn len(&self) -> usize {
+    self.data.len()
+}
+
+/// Parses the input using [`FromStr`] trait.
+/// Check [`Error`] for possible failures.
+///
+/// [`FromStr`]: std::str::FromStr
+pub fn parse<T: FromStr>(input: &str) -> Result<T, Error> {
+    // ...
+}
+```
+
+## Link Syntax
+
+| Syntax | Links To | Example |
+|--------|----------|---------|
+| `[Name]` | Item in scope | `[Vec]`, `[Option]` |
+| `[path::Name]` | Fully qualified item | `[std::vec::Vec]` |
+| `[Self::method]` | Method on current type | `[Self::new]` |
+| `[Type::method]` | Method on other type | `[String::new]` |
+| `[Type::CONST]` | Associated constant | `[usize::MAX]` |
+| `[text](path)` | Custom text | `[see here](Self::len)` |
+
+## Common Patterns
+
+### Linking to Self Members
+
+```rust
+impl Buffer {
+    /// Creates an empty buffer.
+    ///
+    /// Use [`with_capacity`](Self::with_capacity) if you know the size.
+    pub fn new() -> Self { /* ... */ }
+    
+    /// Creates a buffer with pre-allocated capacity.
+    ///
+    /// See [`new`](Self::new) for the default constructor.
+    pub fn with_capacity(cap: usize) -> Self { /* ... */ }
+}
+```
+
+### Linking to Trait Methods
+
+```rust
+/// Converts to a string representation.
+///
+/// This is the implementation of [`Display::fmt`](std::fmt::Display::fmt).
+impl Display for MyType {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        // ...
+    }
+}
+```
+
+### Disambiguation
+
+When names conflict, use suffixes:
+
+```rust
+/// See [`foo()`](fn@foo) for the function and [`foo`](mod@foo) for the module.
+
+/// Works with [`Error`](struct@Error) struct or [`Error`](trait@Error) trait.
+```
+
+| Suffix | Item Type |
+|--------|-----------|
+| `fn@` | Function |
+| `mod@` | Module |
+| `struct@` | Struct |
+| `enum@` | Enum |
+| `trait@` | Trait |
+| `type@` | Type alias |
+| `const@` | Constant |
+| `macro@` | Macro |
+
+### Reference-Style Links
+
+For repeated links or long paths:
+
+```rust
+/// Parses using [`serde`] with [`Deserialize`] trait.
+/// Returns a [`Result`] that may contain [`Error`].
+///
+/// [`serde`]: https://serde.rs
+/// [`Deserialize`]: serde::Deserialize
+/// [`Result`]: std::result::Result
+/// [`Error`]: crate::Error
+```
+
+## Verification
+
+Enable link checking in CI:
+
+```bash
+RUSTDOCFLAGS="-D warnings" cargo doc --no-deps
+```
+
+This fails if any intra-doc links are broken.
+
+## See Also
+
+- [doc-all-public](./doc-all-public.md) - Documenting public items
+- [doc-examples-section](./doc-examples-section.md) - Adding examples
+- [doc-errors-section](./doc-errors-section.md) - Documenting errors

package/template/agent/skills/rust-developer/references/rust-rules/doc-link-types.md

@@ -0,0 +1,169 @@
+# doc-link-types
+
+> Use intra-doc links to connect related types and functions
+
+## Why It Matters
+
+Intra-doc links (`[`TypeName`]`) create clickable references in generated documentation. They enable navigation between related items, verify that referenced items exist at compile time, and update automatically when items are renamed. Plain text references become stale and unclickable.
+
+## Bad
+
+```rust
+/// Parses input and returns a ParseResult.
+/// 
+/// See also: ParseError for error types.
+/// Uses the Tokenizer internally.
+pub fn parse(input: &str) -> ParseResult {
+    // "ParseResult", "ParseError", "Tokenizer" are not clickable
+    // No verification they exist
+}
+```
+
+## Good
+
+```rust
+/// Parses input and returns a [`ParseResult`].
+///
+/// # Errors
+///
+/// Returns [`ParseError::InvalidSyntax`] if the input contains invalid tokens.
+/// Returns [`ParseError::UnexpectedEof`] if the input ends prematurely.
+///
+/// # Related
+///
+/// - [`Tokenizer`] - The underlying tokenizer used by this parser
+/// - [`parse_file`] - Convenience function for parsing files
+/// - [`ParseOptions`] - Configuration options for parsing
+pub fn parse(input: &str) -> ParseResult {
+    // All links are clickable and verified
+}
+```
+
+## Link Syntax
+
+```rust
+/// Basic link to type in same module
+/// See [`MyType`] for details.
+
+/// Link to method
+/// Use [`MyType::new`] to create instances.
+
+/// Link to associated type
+/// Returns [`Iterator::Item`].
+
+/// Link to module
+/// See the [`parser`] module.
+
+/// Link to external crate type
+/// Works with [`std::collections::HashMap`].
+
+/// Link with custom text
+/// See [the parser][`parse`] for details.
+
+/// Link to module item
+/// See [`crate::utils::helper`].
+
+/// Link to parent module item
+/// See [`super::Parent`].
+```
+
+## Common Patterns
+
+```rust
+/// A configuration builder.
+///
+/// # Example
+///
+/// ```
+/// use my_crate::Config;
+///
+/// let config = Config::builder()
+///     .timeout(30)
+///     .build()?;
+/// ```
+///
+/// # Methods
+///
+/// - [`Config::builder`] - Create a new builder
+/// - [`Config::default`] - Create with defaults
+///
+/// # Related Types
+///
+/// - [`ConfigBuilder`] - The builder returned by [`Config::builder`]
+/// - [`ConfigError`] - Errors that can occur when building
+pub struct Config { ... }
+
+impl Config {
+    /// Creates a new [`ConfigBuilder`].
+    ///
+    /// This is equivalent to [`ConfigBuilder::new`].
+    pub fn builder() -> ConfigBuilder { ... }
+}
+```
+
+## Linking to Trait Items
+
+```rust
+/// Implements [`Iterator`] for lazy evaluation.
+///
+/// The [`Iterator::next`] method advances the cursor.
+/// 
+/// For parallel iteration, see [`rayon::ParallelIterator`].
+pub struct MyIterator { ... }
+
+impl Iterator for MyIterator {
+    /// Advances and returns the next value.
+    ///
+    /// See also [`Iterator::nth`] for skipping elements.
+    fn next(&mut self) -> Option<Self::Item> { ... }
+}
+```
+
+## Broken Link Detection
+
+```bash
+# Catch broken intra-doc links
+RUSTDOCFLAGS="-D warnings" cargo doc
+
+# Or in CI
+cargo doc --no-deps 2>&1 | grep "warning: unresolved link"
+```
+
+```toml
+# Cargo.toml - deny broken links
+[lints.rustdoc]
+broken_intra_doc_links = "deny"
+```
+
+## Module-Level Documentation
+
+```rust
+//! # Parser Module
+//!
+//! This module provides parsing utilities.
+//!
+//! ## Main Types
+//!
+//! - [`Parser`] - The main parser struct
+//! - [`Token`] - Tokens produced by tokenization
+//! - [`Ast`] - The abstract syntax tree
+//!
+//! ## Functions
+//!
+//! - [`parse`] - Parse a string
+//! - [`parse_file`] - Parse a file
+//!
+//! ## Errors
+//!
+//! All functions return [`ParseError`] on failure.
+
+pub struct Parser { ... }
+pub enum Token { ... }
+pub struct Ast { ... }
+```
+
+## See Also
+
+- [doc-examples-section](./doc-examples-section.md) - Code examples in docs
+- [err-doc-errors](./err-doc-errors.md) - Documenting errors
+- [lint-deny-correctness](./lint-deny-correctness.md) - Lint settings

package/template/agent/skills/rust-developer/references/rust-rules/doc-module-inner.md

@@ -0,0 +1,116 @@
+# doc-module-inner
+
+> Use `//!` for module-level documentation
+
+## Why It Matters
+
+Inner doc comments (`//!`) document the module itself, not the next item. They appear at the top of module files and describe the module's purpose, contents, and usage patterns. This helps users understand what a module provides before diving into individual items.
+
+Module docs are the first thing users see in `cargo doc` when navigating to a module.
+
+## Bad
+
+```rust
+// This module handles authentication
+// It provides JWT and session-based auth
+
+mod auth;
+
+pub use auth::*;
+```
+
+```rust
+// auth.rs
+/// Authentication utilities  // Wrong: this documents nothing useful
+use std::collections::HashMap;
+
+pub struct Session { /* ... */ }
+```
+
+## Good
+
+```rust
+//! Authentication and authorization utilities.
+//!
+//! This module provides multiple authentication strategies:
+//!
+//! - [`JwtAuth`] - JSON Web Token based authentication
+//! - [`SessionAuth`] - Cookie-based session authentication
+//! - [`ApiKeyAuth`] - API key authentication for services
+//!
+//! # Examples
+//!
+//! ```
+//! use my_crate::auth::{JwtAuth, Authenticator};
+//!
+//! let auth = JwtAuth::new("secret-key");
+//! let token = auth.generate_token(&user)?;
+//! ```
+//!
+//! # Feature Flags
+//!
+//! - `jwt` - Enables JWT authentication (enabled by default)
+//! - `sessions` - Enables session-based authentication
+
+use std::collections::HashMap;
+
+pub struct Session { /* ... */ }
+```
+
+## Where to Use Inner Docs
+
+| Location | Purpose |
+|----------|---------|
+| `lib.rs` | Crate-level documentation (appears on crate root) |
+| `mod.rs` | Module documentation for directory modules |
+| `module.rs` | Module documentation for single-file modules |
+
+## Crate Root Example
+
+```rust
+//! # My Awesome Crate
+//!
+//! `my_crate` provides utilities for handling complex workflows.
+//!
+//! ## Quick Start
+//!
+//! ```rust
+//! use my_crate::prelude::*;
+//!
+//! let workflow = Workflow::builder()
+//!     .add_step(Step::new("fetch"))
+//!     .add_step(Step::new("process"))
+//!     .build();
+//! ```
+//!
+//! ## Modules
+//!
+//! - [`workflow`] - Core workflow engine
+//! - [`steps`] - Built-in workflow steps
+//! - [`prelude`] - Common imports
+//!
+//! ## Feature Flags
+//!
+//! | Feature | Description |
+//! |---------|-------------|
+//! | `async` | Async workflow execution |
+//! | `serde` | Serialization support |
+
+pub mod workflow;
+pub mod steps;
+pub mod prelude;
+```
+
+## Key Sections for Module Docs
+
+1. **Brief description** - One-line summary
+2. **Overview** - What the module provides
+3. **Examples** - How to use it
+4. **Feature flags** - Optional functionality
+5. **See Also** - Related modules
+
+## See Also
+
+- [doc-all-public](./doc-all-public.md) - Documenting public items
+- [doc-examples-section](./doc-examples-section.md) - Adding examples
+- [doc-cargo-metadata](./doc-cargo-metadata.md) - Crate metadata

package/template/agent/skills/rust-developer/references/rust-rules/doc-panics-section.md

@@ -0,0 +1,128 @@
+# doc-panics-section
+
+> Include `# Panics` section for functions that can panic
+
+## Why It Matters
+
+Panics are exceptional conditions that crash the program (or unwind the stack). Users need to know when a function might panic so they can ensure preconditions are met or avoid the function in contexts where panics are unacceptable (e.g., `no_std`, embedded, FFI).
+
+If a function can panic, document exactly when.
+
+## Bad
+
+```rust
+/// Returns the element at the given index.
+pub fn get(index: usize) -> &T {
+    &self.data[index]  // Panics if out of bounds - not documented!
+}
+
+/// Divides two numbers.
+pub fn divide(a: i32, b: i32) -> i32 {
+    a / b  // Panics on division by zero - not documented!
+}
+```
+
+## Good
+
+```rust
+/// Returns the element at the given index.
+///
+/// # Panics
+///
+/// Panics if `index` is out of bounds (i.e., `index >= self.len()`).
+///
+/// # Examples
+///
+/// ```
+/// let v = vec![1, 2, 3];
+/// assert_eq!(v.get(1), &2);
+/// ```
+pub fn get(&self, index: usize) -> &T {
+    &self.data[index]
+}
+
+/// Divides two numbers.
+///
+/// # Panics
+///
+/// Panics if `divisor` is zero.
+///
+/// For a non-panicking version, use [`checked_divide`].
+pub fn divide(dividend: i32, divisor: i32) -> i32 {
+    dividend / divisor
+}
+
+/// Divides two numbers, returning `None` if the divisor is zero.
+pub fn checked_divide(dividend: i32, divisor: i32) -> Option<i32> {
+    if divisor == 0 {
+        None
+    } else {
+        Some(dividend / divisor)
+    }
+}
+```
+
+## Common Panic Conditions
+
+| Operation | Panic Condition |
+|-----------|-----------------|
+| Index access `[i]` | Index out of bounds |
+| Division `/`, `%` | Division by zero |
+| `.unwrap()` | `None` or `Err` value |
+| `.expect()` | `None` or `Err` value |
+| `slice::split_at(mid)` | `mid > len` |
+| `Vec::remove(i)` | `i >= len` |
+| Overflow (debug) | Integer overflow |
+
+## Pattern: Panic vs Return Error
+
+Document why you chose to panic vs return `Result`:
+
+```rust
+/// Creates a new buffer with the given capacity.
+///
+/// # Panics
+///
+/// Panics if `capacity` is zero. A buffer must have at least
+/// one byte of capacity.
+///
+/// This panics rather than returning an error because a zero-capacity
+/// buffer represents a programming error, not a runtime condition.
+pub fn new(capacity: usize) -> Self {
+    assert!(capacity > 0, "capacity must be non-zero");
+    // ...
+}
+```
+
+## Pattern: Debug-Only Panics
+
+```rust
+/// Adds an item to the collection.
+///
+/// # Panics
+///
+/// In debug builds, panics if the collection is at capacity.
+/// In release builds, this is a no-op when at capacity.
+pub fn push(&mut self, item: T) {
+    debug_assert!(self.len < self.capacity, "collection at capacity");
+    // ...
+}
+```
+
+## Provide Non-Panicking Alternatives
+
+When documenting a panicking function, point to safe alternatives:
+
+```rust
+/// # Panics
+///
+/// Panics if the index is out of bounds.
+///
+/// For a non-panicking version, use [`get`] which returns `Option<&T>`.
+```
+
+## See Also
+
+- [doc-errors-section](./doc-errors-section.md) - Documenting errors
+- [doc-safety-section](./doc-safety-section.md) - Documenting unsafe
+- [err-result-over-panic](./err-result-over-panic.md) - Preferring Result

package/template/agent/skills/rust-developer/references/rust-rules/doc-question-mark.md

@@ -0,0 +1,136 @@
+# doc-question-mark
+
+> Use `?` in examples, not `.unwrap()`
+
+## Why It Matters
+
+Doc examples should model best practices. Using `.unwrap()` teaches users to ignore errors, while `?` demonstrates proper error propagation. Examples with `?` also fail the doctest if an error occurs, catching bugs in documentation.
+
+Rust doctests wrap examples in a function that returns `Result<(), E>` by default when you use `?`, making this pattern easy to adopt.
+
+## Bad
+
+```rust
+/// Reads a configuration file.
+///
+/// # Examples
+///
+/// ```
+/// let config = Config::from_file("config.toml").unwrap();
+/// println!("{:?}", config.database_url);
+/// ```
+pub fn from_file(path: &str) -> Result<Config, Error> {
+    // ...
+}
+
+/// Fetches data from the API.
+///
+/// # Examples
+///
+/// ```
+/// let client = Client::new();
+/// let response = client.get("https://api.example.com").unwrap();
+/// let data: Data = response.json().unwrap();
+/// ```
+pub async fn get(&self, url: &str) -> Result<Response, Error> {
+    // ...
+}
+```
+
+## Good
+
+```rust
+/// Reads a configuration file.
+///
+/// # Examples
+///
+/// ```
+/// # use my_crate::{Config, Error};
+/// # fn main() -> Result<(), Error> {
+/// let config = Config::from_file("config.toml")?;
+/// println!("{:?}", config.database_url);
+/// # Ok(())
+/// # }
+/// ```
+pub fn from_file(path: &str) -> Result<Config, Error> {
+    // ...
+}
+
+/// Fetches data from the API.
+///
+/// # Examples
+///
+/// ```no_run
+/// # use my_crate::{Client, Data, Error};
+/// # async fn example() -> Result<(), Error> {
+/// let client = Client::new();
+/// let response = client.get("https://api.example.com").await?;
+/// let data: Data = response.json().await?;
+/// # Ok(())
+/// # }
+/// ```
+pub async fn get(&self, url: &str) -> Result<Response, Error> {
+    // ...
+}
+```
+
+## Doctest Wrapper Pattern
+
+Rust wraps doc examples in a function. You can make this explicit:
+
+```rust
+/// # Examples
+///
+/// ```
+/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
+/// let value = parse_config("key=value")?;
+/// assert_eq!(value.key, "value");
+/// # Ok(())
+/// # }
+/// ```
+```
+
+Or use the implicit wrapper (Rust 2021+):
+
+```rust
+/// # Examples
+///
+/// ```
+/// # use my_crate::parse_config;
+/// let value = parse_config("key=value")?;
+/// assert_eq!(value.key, "value");
+/// # Ok::<(), my_crate::Error>(())
+/// ```
+```
+
+## When to Use `.unwrap()`
+
+There are specific cases where `.unwrap()` is acceptable in examples:
+
+```rust
+/// # Examples
+///
+/// ```
+/// // Static regex that is known at compile time to be valid
+/// let re = Regex::new(r"^\d{4}-\d{2}-\d{2}$").unwrap();
+///
+/// // Parsing a literal that cannot fail
+/// let n: i32 = "42".parse().unwrap();
+/// ```
+```
+
+But still prefer `?` when demonstrating error handling patterns.
+
+## Comparison
+
+| Pattern | Behavior on Error | Teaches |
+|---------|-------------------|---------|
+| `.unwrap()` | Panics with generic message | Bad habits |
+| `.expect()` | Panics with custom message | Slightly better |
+| `?` | Propagates error, test fails | Best practices |
+
+## See Also
+
+- [doc-examples-section](./doc-examples-section.md) - Writing examples
+- [doc-hidden-setup](./doc-hidden-setup.md) - Hiding setup code
+- [err-question-mark](./err-question-mark.md) - Error propagation