agy-superpowers 5.2.1 → 5.2.3

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

@@ -1,122 +0,0 @@
-# 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

@@ -1,161 +0,0 @@
-# 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

@@ -1,149 +0,0 @@
-# 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

@@ -1,138 +0,0 @@
-# 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