Правила оформления документации: кавычки, заголовки, единый источник

Title:

URL Source: https://raw.githubusercontent.com/pydantic/pydantic-ai/main/agent_docs/documentation.md

Markdown Content: # Documentation

> Rules for writing docstrings, comments, user-facing documentation, and maintaining documentation accuracy

**When to check**: When writing or updating documentation, comments, or docstrings

## Rules

<!-- rule:272 --> - Wrap all code identifiers in docstrings with single backticks — parameters, variables, functions, classes, types, fields, API terms — Ensures consistent docstring formatting and makes code elements visually distinct for better readability <!-- rule:339 --> - Remove comments that restate obvious code — explain non-obvious intent, edge cases, or constraints instead — Reduces noise and maintenance burden while preserving information that can't be inferred from self-documenting code <!-- rule:35 --> - Use Markdown heading syntax (`##`, `###`, `####`) instead of bold text for sections — preserves semantic structure and document hierarchy — Proper heading levels enable navigation, accessibility, and consistent documentation structure across all `.md` files <!-- rule:396 --> - Establish one canonical source per topic and link to it — prevents inconsistency and maintenance burden — Documentation that's duplicated across locations becomes outdated differently, creating contradictions and requiring multiple updates for every change <!-- rule:34 --> - Link to official provider/project docs instead of duplicating model lists, features, or setup details — prevents stale documentation and reduces maintenance burden — Exhaustive inline lists become outdated quickly; authoritative external sources stay current and reduce maintenance <!-- rule:138 --> - Update all related docs in the same PR when changing functionality, APIs, or capabilities — includes docstrings, comments, external docs (e.g., `ai.pydantic.dev`), and API references — Prevents documentation drift that misleads users about actual behavior, limitations, or API contracts <!-- rule:107 --> - Register new `docs/` files in `docs/navigation.yml` — Keeps the published pydantic.dev/docs/ai navigation complete and prevents orphaned pages or route drift <!-- rule:31 --> - Use consistent terminology across code, docs, comments, and errors (e.g., `freeform` vs `free-form`, `messages` vs `last message`) — prevents user confusion and makes codebase searchable — Inconsistent terminology fragments documentation searches, confuses users trying to map concepts between docs and code, and signals poor API design quality <!-- rule:76 --> - Prefix future work with `TODO:` and link workarounds to upstream/internal issues — enables tracking and cleanup when conditions change — Explicit markers with tracking links prevent abandoned workarounds and make technical debt actionable and removable when upstream fixes land <!-- rule:611 --> - Reference issues and PRs in comments and docstrings with the full URL (`https://github.com/pydantic/pydantic-ai/issues/1234`), not the `#1234` shorthand — The shorthand isn't clickable outside GitHub's own rendering (IDEs, generated API docs, plain-text views), so a full link stays navigable wherever the code is read <!-- rule:386 --> - Keep docs and implementation in sync — when they conflict, explicitly decide which to update and fix it — Prevents user confusion and wasted debugging time when documented behavior doesn't match actual behavior; applies to params, config options, component characteristics, and especially test docstrings which must describe what's actually validated <!-- rule:106 --> - Document provider feature support with 'Supported by:' sections — link each provider, list supported/unsupported, distinguish variants (Google Gemini vs Google Cloud (formerly known as Vertex AI)), include syntax/config/permissions — Prevents users from attempting unsupported features and enables quick evaluation of provider capabilities without trial-and-error testing across multiple providers <!-- rule:750 --> - Document all defaults comprehensively: explicit values, fallback chains, compatibility tradeoffs (backward/forward), and implicit/conditional defaults from parameter interactions — Prevents API confusion and misuse by making fallback behavior, override precedence, and compatibility constraints discoverable in docstrings rather than requiring code archaeology <!-- rule:150 --> - Comment non-obvious conditionals — explain edge cases, error handling, and state-based logic — Intent isn't always clear from code alone; comments prevent confusion during maintenance and debugging <!-- rule:368 --> - Document what code does now, not what it used to do — skip historical references like "original", "old", "legacy", or "this used to do X" — Historical comments become outdated noise that confuses future readers; focus on current behavior and rationale <!-- rule:801 --> - Keep documentation concise—focus on essential information, not implementation details or edge cases — Reduces maintenance burden and improves readability by avoiding unnecessary detail that becomes outdated or clutters the docs <!-- rule:313 --> - Document workarounds with (1) expected behavior, (2) why it fails, and (3) that it compensates for external constraints — Prevents future developers from "fixing" workarounds that address API limitations, spec non-compliance, or external bugs — these look like code smells but are actually intentional compensations <!-- rule:623 --> - Avoid line numbers in comments/docstrings — use function/class names instead — Line numbers become stale immediately when code changes, breaking the reference and misleading readers <!-- rule:656 --> - Document new user-facing features in dedicated sections where users naturally encounter them, not just in docstrings — Users discover features through conceptual docs and guides, not API references — ensures feature discoverability and proper context <!-- rule:-4 --> - Link to a Pydantic AI Harness capability via its docs page at `https://pydantic.dev/docs/ai/harness/<slug>/` (e.g. `https://pydantic.dev/docs/ai/harness/exa-search/`, `https://pydantic.dev/docs/ai/harness/compaction/`), not its GitHub repo/README — the harness has published docs; only fall back to a GitHub link when a capability has no docs page yet — Gives readers rendered, canonical docs instead of raw source, and matches how the rest of the repo references the harness (`https://pydantic.dev/docs/ai/harness/`)