Refine docstring structure guidance

[leynos]

Summary

This branch clarifies the repository's docstring policy so all public functions, classes, and methods receive comprehensive NumPy-style documentation while private helpers remain proportionate to their scope.

It also makes a longer private-helper explanation a prompt to inspect command/query boundaries, CQRS and cohesion before retaining the paragraph, and records that convention in the developers' guide so contributors can discover it alongside the Python linting policy.

Review walkthrough

• Start with AGENTS.md for the complete public API requirement, private-helper decision rules, and selective use of structured NumPy-style sections.
• Then review docs/developers-guide.md for the contributor-facing copy of the docstring structure convention.

Validation

• make fmt: passed.
• make markdownlint: passed.
• nixie --no-sandbox AGENTS.md docs/developers-guide.md: passed.
• make nixie: passed.

References

• Lody session

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

Update AGENTS.md to define comprehensive NumPy-style docstrings for public methods, concise documentation for private helpers, and selective use of structured sections for non-obvious behaviour.

Changes

Docstring Guidance

Layer / File(s)	Summary
Public and private docstring rules AGENTS.md	Apply expanded NumPy-style documentation requirements to public methods, examples where appropriate, and concise, selectively structured guidance for private helpers.

Possibly related PRs

• leynos/mdtablefix#317: Update the related AGENTS.md documentation guidance template.

Poem

Public methods speak in sections clear,
Private helpers keep their purpose near.
Examples bloom where meaning grows,
Concise notes guide hidden flows.
NumPy shapes the words we write.

🚥 Pre-merge checks | ✅ 19 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Performance And Resource Use	❓ Inconclusive	Pending repo inspection; verify the change is documentation-only and carries no performance-sensitive code paths.	Inspect the diff and AGENTS.md, then confirm whether any loops, I/O, allocations, or blocking work were introduced.

✅ Passed checks (19 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Testing (Overall)	✅ Passed	PASS: The commit only updates AGENTS.md guidance; no product code or behavioural paths changed, so there is no new functionality needing tests.
User-Facing Documentation	✅ Passed	Pass: keep the change confined to AGENTS.md; no user-facing functionality changed, so docs/users-guide.md needs no update.
Developer Documentation	✅ Passed	Accept this: the commit only edits AGENTS.md docstring guidance; no APIs, architecture, tooling, roadmap, or execplan changed, so no extra developer docs are required.
Module-Level Documentation	✅ Passed	Review only AGENTS.md; no module files changed, so the module-level docstring rule is not applicable to this PR.
Testing (Unit And Behavioural)	✅ Passed	PASS: only AGENTS.md documentation changed; no runtime behaviour or APIs were altered, so unit/behavioural tests are not applicable.
Testing (Property / Proof)	✅ Passed	The PR only amends documentation policy; it introduces no executable invariant, state transition, or proof obligation that would warrant property or proof tests.
Testing (Compile-Time / Ui)	✅ Passed	Docs-only AGENTS.md change; no compile-time or UI behaviour is introduced, so trybuild or snapshot coverage is not applicable.
Unit Architecture	✅ Passed	Only AGENTS.md was changed; no runtime code, tests, or dependency boundaries were altered, so the architecture check is not applicable.
Domain Architecture	✅ Passed	PASS: HEAD only changes AGENTS.md documentation; no domain, adapter, persistence, or transport code was modified, so the architecture boundary remains unaffected.
Observability	✅ Passed	Pass this check: only AGENTS.md guidance changed; no operational code, logging, metrics, tracing, or alerts changed.
Security And Privacy	✅ Passed	PASS: The only change is AGENTS.md guidance; it adds docstring policy text and introduces no secrets, auth gaps, permission changes, injection risks, or sensitive-data exposure.
Concurrency And State	✅ Passed	Pass: HEAD changes only AGENTS.md docstring policy; no shared state, async, locking, or task-lifetime code was modified.
Architectural Complexity And Maintainability	✅ Passed	Only AGENTS.md prose changed; no new code abstractions, layers, dependencies, or cycles were introduced.
Rust Compiler Lint Integrity	✅ Passed	Only AGENTS.md changed; no Rust sources, lint suppressions, or clone-related code were touched.
Title check	✅ Passed	The title matches the PR’s docstring policy refinements.
Description check	✅ Passed	The description clearly relates to the docstring guidance updates and validation steps.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docstring-guidance

---

_{Comment @coderabbitai help to get the list of available commands.}

[sourcery-ai]

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

Refines the repository’s documentation guidelines to distinguish between comprehensive NumPy-style docstrings for public methods and concise, selectively structured docstrings for private helpers and tests, emphasizing cohesion, CQRS boundaries, and meaningful examples.

File-Level Changes

Change	Details	Files
Clarified and expanded docstring and documentation policies for public methods, private helpers, and tests.	Replaced the generic requirement for clear examples in function documentation with a mandate that public methods use comprehensive NumPy-style docstrings, including examples where appropriate. Added guidance that private helpers should prefer single-line docstrings, and that longer explanations should trigger review of command/query separation, CQRS boundaries, and cohesion, with suggestions to split or extract helpers when responsibilities are conflated. Introduced a rule that structured NumPy-style sections should be used for private helpers only when they describe non-obvious behaviour. Reworded test documentation guidance to emphasize omitting examples that merely restate test logic.	AGENTS.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Sorry @leynos, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 41cfad6ab8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@AGENTS.md`:
- Around line 22-24: Update the documentation requirement in AGENTS.md to refer
to public APIs and explicitly include public functions, classes, and methods,
while preserving the existing NumPy-style docstring and example requirements.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 4d47af54-4146-4d4b-a4e1-0140db6b839c

📥 Commits

Reviewing files that changed from the base of the PR and between 302858c and 41cfad6.

📒 Files selected for processing (1)

• AGENTS.md

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• leynos/shared-actions (auto-detected)
• leynos/pylint-pypy-shim (auto-detected)
• leynos/whitaker (auto-detected)

[codescene-access]

No quality gates enabled for this code.

[sourcery-ai]

Sorry @leynos, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery