docs(API): improve get /projects/{project_id}/documents documentation

[Stephen Lumenta (sbl)]

Improves the documentation for get /projects/{project_id}/documents: sharper descriptions, parameter docs, error responses, and usage examples.

Drafted with AI assistance and grounded in the API implementation. Please review for technical accuracy before merging; nothing is merged automatically.

🤖 Generated with Claude Code

[github-actions]

API changelog (oasdiff)

Doc-only edits (descriptions, examples) do not appear here.

10 changes: 0 error, 0 warning, 10 info
info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/api_name` became required for the status `200`

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/default_encoding` became required for the status `200`

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/default_file` became required for the status `200`

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/description` became required for the status `200`

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/exportable` became required for the status `200`

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/extension` became required for the status `200`

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/importable` became required for the status `200`

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/includes_locale_information` became required for the status `200`

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/name` became required for the status `200`

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/renders_default_locale` became required for the status `200`

[Stephen Lumenta (sbl)]

This PR replaces #1178, which was closed after reviews from jablan and theSoenke.

Feedback addressed from #1178:

Reviewer	Comment	Status
theSoenke	"The policy should not be part of the API docs"	✅ Fixed
theSoenke	"per_page and rate limit details do not need to be repeated per endpoint"	✅ Fixed
jablan	"I don't think it's helpful to say the list is paginated here"	✅ Fixed
jablan	"Pagination information is superfluous here" (RFC 5988 / Link header sentence)	✅ Fixed
jablan	"Please do not expose identifier names from internal applications"	✅ Fixed
jablan	"Rate limiting applies universally and is explained on a dedicated place"	✅ Fixed

What changed: The description is fully rewritten. All six flagged items are removed:

• No DocumentPolicy#list_documents? or any internal class/policy name
• No pagination prose ("returns a paginated list", RFC 5988, Link header)
• No per_page cap or default
• No rate-limit pitfall

What remains is endpoint-specific: what a document is, when you'd use this endpoint, how the q prefix match works, and the auth requirement.

🤖 Generated with Claude Code