Skip to content

Document the PageResult attributes in a Returns section - #15

Merged
arrufat merged 1 commit into
mainfrom
generated-returns-section
Oct 1, 2026
Merged

arrufat merged 1 commit into
mainfrom
generated-returns-section

Conversation

@arrufat

@arrufat arrufat commented Oct 1, 2026

Copy link
Copy Markdown
Collaborator

Closes #6, the last part of item 1.

#14 annotated the eight tools that declare an outputSchema as -> PageResult, but the docstrings still did not say what a PageResult holds, and the issue started from the Returns column the retired reference page had. generate_methods.py now ends those docstrings with a Google-style section built from the output schema:

Returns:
    PageResult: The sentence above, with these attributes (None when absent):

    - `url`: URL of the page the call left loaded.
    - `http_status`: Response status of that page's own document. Absent when no response has arrived. 4xx/5xx means an error page, not the content.
    - `title`: Document title. Empty or absent when the page has none.

The descriptions are the browser's, so they change with the schema. The header line says "None when absent" because the schema describes the wire, where a missing field is left out, while PageResult sets the attribute to None.

Each property is checked against PageResult's annotations. If the browser adds an output field the class doesn't expose, generation fails, so the docstring can't name an attribute that isn't there. The CI drift check runs the generator against nightly, so that failure surfaces on the next PR.

Rendered both ways: pdoc puts it under a Returns heading as a list, and the docs site's generate-python-reference.py (run against this branch) emits the same list under **Returns:** for all eight Session methods.

The data tools stay -> Any with no Returns section. MCP gives no shape for them short of an outputSchema, and browser#3694 deliberately left that off, so a typed return for them would need either that browser change or a hand-written map here.

The methods annotated `-> PageResult` now say what that result carries:
a Google-style `Returns:` section lists `url`, `http_status` and `title`,
each described by the tool's outputSchema property. pdoc and the docs
site render it as a list under Returns, which is the column the retired
hand-written reference page had.

The attribute names come from the schema, so generation stops if the
browser adds an output property that PageResult does not expose, instead
of documenting an attribute that is not there.

Closes #6.
@arrufat
arrufat merged commit ac09e73 into main Oct 1, 2026
11 checks passed
@arrufat
arrufat deleted the generated-returns-section branch October 1, 2026 10:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Make the generated methods self-documenting: return shapes and the Session conventions

1 participant