view release on metacpan or  search on metacpan

.claude/agents/pod-writer.md  view on Meta::CPAN

| `=example` | Usage examples | `=example Basic Usage` |
| `=seealso` | Related modules | `=seealso L<Other::Module>` |

## Complete Example

```perl
package WWW::Example::Client;
# ABSTRACT: Client for Example API

use Moo;
use namespace::clean;

=head1 SYNOPSIS

    use WWW::Example::Client;

    my $client = WWW::Example::Client->new(
        token => $ENV{EXAMPLE_TOKEN},
    );
    my $data = $client->fetch('/users');

=head1 DESCRIPTION

HTTP client for the Example API with automatic retry and caching.

=cut

has base_url => ( is => 'ro', default => 'https://api.example.com' );

=attr base_url

API base URL. Defaults to C<https://api.example.com>.

=cut

has token => ( is => 'ro', required => 1 );

=attr token

API authentication token. Required.

=cut

has timeout => ( is => 'ro', default => 30 );

=attr timeout

Request timeout in seconds. Defaults to C<30>.

=cut

sub fetch {
    my ($self, $path) = @_;
    # implementation
}

=method fetch

    my $data = $client->fetch($path);

Fetch data from API endpoint. Returns decoded JSON.

=cut

sub search {
    my ($self, $query) = @_;
    # implementation
}

=method search

    my $results = $client->search($query);

Search the API. Returns ArrayRef of results.

=cut

1;
```

## Rules

1. **Inline POD**: Write `=attr` directly after `has`, `=method` directly after `sub`
2. **No NAME section**: PodWeaver generates from `# ABSTRACT:`
3. **No AUTHOR/LICENSE**: Auto-generated from dist.ini
4. **No SUPPORT/CONTRIBUTING**: Auto-generated by @Author::GETTY
5. **No `=head1 ATTRIBUTES/METHODS`**: Commands transform to `=head2` inline
6. **End with `1;`**: No `__END__`, POD is inline throughout
7. **Code examples**: 4-space indent in POD
8. **Cross-references**: Use `L<Module::Name>` and `L<method_name|/method_name>`
9. **Inline code**: Use `C<code>` for variable names, defaults, method names
10. **Keep it concise**: Document what's not obvious from the code
11. **Module links**: ALWAYS use `L<Module::Name>` — NEVER manually link to metacpan URLs (e.g. `L<Module|https://metacpan.org/pod/Module>` is WRONG). POD renderers auto-link module names to MetaCPAN. Only use explicit URLs for non-CPAN resources (...

## Documentation Tree (Cross-Linking)

**Goal**: Create a navigable documentation tree where users can reach any module by clicking through POD links. 99% of modules should be reachable from the main module.

### Navigation Strategy

1. **Build the module hierarchy first**: Before writing POD, analyze all modules in the distribution to understand the tree structure.

2. **Every module must link to**:
   - Its parent namespace (if exists)
   - Its child namespaces (if any)
   - Related modules it uses or returns

3. **Link syntax**:
   - Same distribution: `L<My::Module::Child>`
   - Same distribution method: `L<My::Module/method_name>`
   - External CPAN: `L<External::Module>`

### SEE ALSO Section

Add `=seealso` (or `=head1 SEE ALSO` for plain distributions) to every module:

```perl
=seealso

=over