agy-superpowers 5.1.4 → 5.1.5

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

@@ -0,0 +1,122 @@
+# doc-errors-section
+
+> Include `# Errors` section for fallible functions
+
+## Why It Matters
+
+Functions returning `Result` can fail in specific, documented ways. The `# Errors` section tells users exactly when and why a function might return an error, enabling them to handle failures appropriately without reading source code.
+
+This is especially critical for library code where users cannot easily inspect implementation details.
+
+## Bad
+
+```rust
+/// Opens a file and reads its contents.
+pub fn read_file(path: &Path) -> Result<String, Error> {
+    // Users have no idea what errors to expect
+}
+
+/// Connects to the database.
+pub async fn connect(url: &str) -> Result<Connection, DbError> {
+    // Multiple failure modes, none documented
+}
+```
+
+## Good
+
+```rust
+/// Opens a file and reads its contents as a UTF-8 string.
+///
+/// # Errors
+///
+/// Returns an error if:
+/// - The file does not exist ([`Error::NotFound`])
+/// - The process lacks permission to read the file ([`Error::PermissionDenied`])
+/// - The file contains invalid UTF-8 ([`Error::InvalidUtf8`])
+pub fn read_file(path: &Path) -> Result<String, Error> {
+    // ...
+}
+
+/// Establishes a connection to the database.
+///
+/// # Errors
+///
+/// This function will return an error if:
+/// - The URL is malformed ([`DbError::InvalidUrl`])
+/// - The database server is unreachable ([`DbError::ConnectionFailed`])
+/// - Authentication fails ([`DbError::AuthenticationFailed`])
+/// - The connection pool is exhausted ([`DbError::PoolExhausted`])
+pub async fn connect(url: &str) -> Result<Connection, DbError> {
+    // ...
+}
+```
+
+## Error Documentation Patterns
+
+### Simple Single Error
+
+```rust
+/// Parses a string as an integer.
+///
+/// # Errors
+///
+/// Returns [`ParseIntError`] if the string is not a valid integer.
+pub fn parse_int(s: &str) -> Result<i64, ParseIntError> {
+    s.parse()
+}
+```
+
+### Multiple Error Variants
+
+```rust
+/// Sends an HTTP request and returns the response.
+///
+/// # Errors
+///
+/// | Error | Condition |
+/// |-------|-----------|
+/// | [`HttpError::Timeout`] | Request exceeded timeout duration |
+/// | [`HttpError::InvalidUrl`] | URL could not be parsed |
+/// | [`HttpError::ConnectionRefused`] | Server refused connection |
+/// | [`HttpError::TlsError`] | TLS handshake failed |
+pub fn send(request: Request) -> Result<Response, HttpError> {
+    // ...
+}
+```
+
+### Propagated Errors
+
+```rust
+/// Loads configuration from a file.
+///
+/// # Errors
+///
+/// Returns an error if:
+/// - The configuration file cannot be read (IO error)
+/// - The file contains invalid TOML syntax
+/// - Required fields are missing from the configuration
+///
+/// The underlying error is wrapped with context about which
+/// configuration file failed to load.
+pub fn load_config(path: &Path) -> Result<Config, anyhow::Error> {
+    // ...
+}
+```
+
+## Linking to Error Types
+
+Use intra-doc links to connect error variants to their definitions:
+
+```rust
+/// # Errors
+///
+/// Returns [`ValidationError::TooShort`] if the input is less than
+/// the minimum length, or [`ValidationError::InvalidChars`] if it
+/// contains forbidden characters.
+```
+
+## See Also
+
+- [doc-panics-section](./doc-panics-section.md) - Documenting panics
+- [err-doc-errors](./err-doc-errors.md) - Error documentation patterns
+- [doc-intra-links](./doc-intra-links.md) - Linking to types

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

@@ -0,0 +1,161 @@
+# doc-examples-section
+
+> Include `# Examples` with runnable code
+
+## Why It Matters
+
+Examples are the most valuable part of documentation. They show users exactly how to use your API. Rust's doc tests ensure examples stay correct as code evolves.
+
+## Bad
+
+```rust
+/// Parses a string into a Foo.
+pub fn parse(s: &str) -> Result<Foo, Error> {
+    // No examples - users have to guess usage
+}
+
+/// A widget for doing things.
+/// 
+/// This widget is very useful.
+pub struct Widget {
+    // Still no examples
+}
+```
+
+## Good
+
+```rust
+/// Parses a string into a Foo.
+///
+/// # Examples
+///
+/// ```
+/// use my_crate::parse;
+///
+/// let foo = parse("hello").unwrap();
+/// assert_eq!(foo.name(), "hello");
+/// ```
+///
+/// Handles empty strings:
+///
+/// ```
+/// use my_crate::parse;
+///
+/// let foo = parse("").unwrap();
+/// assert!(foo.is_empty());
+/// ```
+pub fn parse(s: &str) -> Result<Foo, Error> {
+    // ...
+}
+```
+
+## Use ? Not unwrap()
+
+```rust
+/// Loads configuration from a file.
+///
+/// # Examples
+///
+/// ```
+/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
+/// use my_crate::Config;
+///
+/// let config = Config::load("config.toml")?;
+/// println!("Port: {}", config.port);
+/// # Ok(())
+/// # }
+/// ```
+pub fn load(path: &str) -> Result<Config, Error> {
+    // ...
+}
+```
+
+## Hide Setup Code
+
+```rust
+/// Processes items from a database.
+///
+/// # Examples
+///
+/// ```
+/// # use my_crate::{Database, Item};
+/// # fn get_db() -> Database { Database::mock() }
+/// let db = get_db();
+/// let items = db.process_items()?;
+/// assert!(!items.is_empty());
+/// # Ok::<(), my_crate::Error>(())
+/// ```
+pub fn process_items(&self) -> Result<Vec<Item>, Error> {
+    // ...
+}
+```
+
+## Multiple Examples
+
+```rust
+/// Creates a new buffer with the specified capacity.
+///
+/// # Examples
+///
+/// Basic usage:
+///
+/// ```
+/// use my_crate::Buffer;
+///
+/// let buf = Buffer::with_capacity(1024);
+/// assert_eq!(buf.capacity(), 1024);
+/// ```
+///
+/// Zero capacity creates an empty buffer:
+///
+/// ```
+/// use my_crate::Buffer;
+///
+/// let buf = Buffer::with_capacity(0);
+/// assert!(buf.is_empty());
+/// ```
+pub fn with_capacity(cap: usize) -> Self {
+    // ...
+}
+```
+
+## Show Error Cases
+
+```rust
+/// Divides two numbers.
+///
+/// # Examples
+///
+/// ```
+/// use my_crate::divide;
+///
+/// assert_eq!(divide(10, 2), Ok(5));
+/// ```
+///
+/// Division by zero returns an error:
+///
+/// ```
+/// use my_crate::{divide, MathError};
+///
+/// assert_eq!(divide(10, 0), Err(MathError::DivisionByZero));
+/// ```
+pub fn divide(a: i32, b: i32) -> Result<i32, MathError> {
+    // ...
+}
+```
+
+## Running Doc Tests
+
+```bash
+# Run all doc tests
+cargo test --doc
+
+# Run doc tests for specific item
+cargo test --doc my_function
+```
+
+## See Also
+
+- [doc-question-mark](doc-question-mark.md) - Use ? in examples
+- [doc-hidden-setup](doc-hidden-setup.md) - Hide setup code with #
+- [doc-errors-section](doc-errors-section.md) - Document error conditions

package/template/agent/skills/rust-developer/references/rust-rules/doc-hidden-setup.md

@@ -0,0 +1,149 @@
+# doc-hidden-setup
+
+> Use `# ` prefix to hide example setup code
+
+## Why It Matters
+
+Doc examples often require setup code (imports, struct initialization, mock data) that distracts from the main point. The `# ` prefix hides lines from rendered documentation while keeping them in the compiled test, showing users only the relevant code.
+
+This keeps examples focused and readable while ensuring they still compile and run.
+
+## Bad
+
+```rust
+/// Processes a batch of items.
+///
+/// # Examples
+///
+/// ```
+/// use my_crate::{Processor, Config, Item};
+/// use std::sync::Arc;
+/// 
+/// let config = Config {
+///     batch_size: 100,
+///     timeout_ms: 5000,
+///     retry_count: 3,
+/// };
+/// let processor = Processor::new(Arc::new(config));
+/// let items = vec![
+///     Item::new("a"),
+///     Item::new("b"),
+///     Item::new("c"),
+/// ];
+/// 
+/// // This is the actual example - buried after 15 lines of setup
+/// let results = processor.process_batch(&items)?;
+/// assert!(results.all_succeeded());
+/// # Ok::<(), my_crate::Error>(())
+/// ```
+pub fn process_batch(&self, items: &[Item]) -> Result<Results, Error> {
+    // ...
+}
+```
+
+## Good
+
+```rust
+/// Processes a batch of items.
+///
+/// # Examples
+///
+/// ```
+/// # use my_crate::{Processor, Config, Item, Error};
+/// # use std::sync::Arc;
+/// # let config = Config { batch_size: 100, timeout_ms: 5000, retry_count: 3 };
+/// # let processor = Processor::new(Arc::new(config));
+/// # let items = vec![Item::new("a"), Item::new("b"), Item::new("c")];
+/// let results = processor.process_batch(&items)?;
+/// assert!(results.all_succeeded());
+/// # Ok::<(), Error>(())
+/// ```
+pub fn process_batch(&self, items: &[Item]) -> Result<Results, Error> {
+    // ...
+}
+```
+
+Users see only:
+
+```rust
+let results = processor.process_batch(&items)?;
+assert!(results.all_succeeded());
+```
+
+## What to Hide
+
+| Hide | Show |
+|------|------|
+| `use` statements | Core API usage |
+| Type definitions | Method calls |
+| Mock/test data setup | Key parameters |
+| Error handling boilerplate | Return value handling |
+| `Ok(())` return | Assertions (sometimes) |
+
+## Pattern: Hiding Multi-Line Setup
+
+```rust
+/// # Examples
+///
+/// ```
+/// # use my_crate::{Client, Request};
+/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
+/// # let client = Client::builder()
+/// #     .timeout(30)
+/// #     .retry(3)
+/// #     .build()?;
+/// let response = client.send(Request::get("/users"))?;
+/// println!("Status: {}", response.status());
+/// # Ok(())
+/// # }
+/// ```
+```
+
+## Pattern: Showing Setup When Relevant
+
+Sometimes setup IS the point—don't hide it:
+
+```rust
+/// Creates a new client with custom configuration.
+///
+/// # Examples
+///
+/// ```
+/// use my_crate::Client;
+///
+/// // Configuration IS the example - show it
+/// let client = Client::builder()
+///     .base_url("https://api.example.com")
+///     .timeout_secs(30)
+///     .max_retries(3)
+///     .build()?;
+/// # Ok::<(), my_crate::Error>(())
+/// ```
+```
+
+## Pattern: `ignore` and `no_run`
+
+For examples that shouldn't run in tests:
+
+```rust
+/// # Examples
+///
+/// ```no_run
+/// # use my_crate::Server;
+/// // This would actually start a server - don't run in tests
+/// let server = Server::bind("0.0.0.0:8080").await?;
+/// server.run().await?;
+/// # Ok::<(), my_crate::Error>(())
+/// ```
+
+/// ```ignore
+/// // Pseudocode or incomplete example
+/// let magic = do_something_undefined();
+/// ```
+```
+
+## See Also
+
+- [doc-examples-section](./doc-examples-section.md) - Writing examples
+- [doc-question-mark](./doc-question-mark.md) - Using `?` in examples
+- [test-doctest-examples](./test-doctest-examples.md) - Doctests as tests

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