Public plugin API module has no module-level contract documentation

[huyhoang171106]

Summary

picard/plugin3/api.py is the public import surface for plugin authors (__all__ defines the exposed API), but it has no module docstring documenting what is stable, how to import from it, or what each exported symbol represents. For an extension API, this increases misuse risk and creates support burden because plugin authors must inspect internals instead of relying on an explicit contract.

Files changed

• picard/plugin3/api.py (modified)

Testing

• Not run in this environment.

Summary

• This is a…
  • Bug fix
  • Feature addition
  • Refactoring
  • Minor / simple change (like a typo)
  • Other
• Describe this change in 1-2 sentences:

Problem

• JIRA ticket (optional): PICARD-XXX

Solution

AI Usage

In accordance with the AI use policy portion of the MetaBrainz Contribution Guidelines, the level of AI/LLM use in the development of this Pull Request is:

• No AI/LLM use
• Minimal use (e.g. autocompletion)
• Moderate use (e.g. suggestions regarding code fragments)
• Significant use (e.g. code structure, tests development, etc.)
• Primarily AI developed
• Other (please specify below)

Action

Additional actions required:

• Update Picard documentation (please include a reference to this PR)
• Other (please specify below)

[Copilot]

Pull request overview

Adds module-level contract documentation to picard.plugin3.api, clarifying that this module is the supported import surface for Plugin API v3 and that symbols in __all__ define the public plugin-facing contract.

Changes:

• Introduced a module docstring describing the stability/import contract for plugin authors.
• Documented the intended usage pattern (import from picard.plugin3.api) and summarized exported symbols.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.