[MbappeWU]

Closes #221.

🤖 AI tooling was used for this PR. The sections were drafted with an AI coding assistant. I checked each entry against the code path it describes and ran the checks below. The commit subject and the changelog bullet carry the 🤖 marker per DEVELOPMENT.md.

What Is This?

Google-style Args:, Returns: and Raises: sections on the public API that docs/api.md renders. mkdocstrings-python parses Google style by default, so the API page now shows parameter, return and exception tables. The existing prose, examples and code fences are unchanged. Only sections were appended, and four one-line docstrings became multi-line to hold them.

Covered: EventEmitter (on, listens_to, add_listener, event_names, emit, once, remove_listener, remove_all_listeners, listeners), AsyncIOEventEmitter (constructor, emit, complete), ExecutorEventEmitter (constructor, shutdown), TrioEventEmitter (constructor, context), uplift, unwrap, pyee.cls.on and evented.

Why Is This?

The issue asks for it, and the API page had none of these sections. A few behaviors were only visible in the code before:

• emit returns whether any handler was attached. On "error" with no listener it raises the first argument if it is an Exception, and PyeeError otherwise.
• on and once return the handler when f is given, and a decorator when it is not.
• remove_listener does nothing for a listener that is not registered.
• TrioEventEmitter raises PyeeError when both nursery and manager are passed, and context raises it when neither is set.
• uplift raises KeyError for an unknown error_handling or proxy_new_listener value. That comes from a dict lookup, not an explicit raise.

Anything We Need To Know?

• Not documented on purpose: pyee.cls.Handler and Handlers, the bookkeeping behind @on. TwistedEventEmitter, wait_for_complete and cancel take no arguments and return nothing, so they get no sections.
• *args and **kwargs on emit and uplift are listed as args and kwargs, the names griffe uses.
• The Conventions section of the AGENTS.md in 🤖 Add AGENTS.md for AI coding agents #220 says the docstrings have no Args, Returns or Raises sections. Whichever of the two lands second, I'll update that line.

Verification

On this branch (Python 3.13, uv):

• just format: no changes. just lint: flake8 clean, Valid file: ./pyproject.toml.
• just check: 0 errors, 0 warnings, 0 informations. just mypy: Success: no issues found in 16 source files.
• just test: 52 passed.
• uv run mkdocs build --strict: builds clean. In the built api/index.html, the counts of Parameters: / Returns: / Raises: go from 0 / 0 / 0 on main to 17 / 35 / 13.
• A throwaway griffe script that lists public callables missing these sections: 32 gaps on main, 3 on this branch (the Handler / Handlers items above).

Questions

• Has the developer read DEVELOPMENT.md?
• Have tests been updated accordingly? (Docstrings only, no behavior change.)
• Have AI assisted commits been marked with a 🤖 emoji?
• Have AI assisted changes been marked with a 🤖 emoji in CHANGELOG.md?
• Does the PR notify the use of AI coding assistants?
• Is the developer's name in the CONTRIBUTORS.md file?

[jfhbrook]

Looks legit. I'm a little picky about prose, so I'll have to read through and make some copy edits. But this is an excellent start! I'll pull it in when I do the next release.

Thanks!

[MbappeWU]

Thanks! Since #220 landed first, I pushed 8c6234a on top of your merge. It changes the AGENTS.md line that said the docstrings have no Args, Returns, or Raises sections, so the guide matches this PR. Tests and mkdocs build --strict still pass.

[jfhbrook]

Merged manually. Cheers!

[jfhbrook]

Releasing in v16.0.0.