search

aip-dev / google.aip.dev

API Improvement Proposals. https://aip.dev/
Other
1.1k stars 501 forks source link

AIP-131 format comment #631

Open gajones155 opened 4 years ago

gajones155 commented 4 years ago

AIP-131 encourages a comment line

  // Format: publishers/{publisher}/books/{book}

but when I generate documentation this results in duplicate lines in the generated HTML documentation, e.g.

"The resource name of the requested account. Format: accounts/{account} It takes the form accounts/{account_id}."

Further, the format differs in that one contains {account} and the other {account_id}. Which format is preferred?

apasel422 commented 4 years ago

Relatedly, for parent fields that can have multiple resource types (due to (google.api.resource_reference).child_type = ...), it seems like it would be better to avoid having to re-list all possible formats.

lukesneeringer commented 4 years ago

but when I generate documentation this results in duplicate lines in the generated HTML documentation, e.g.

I did not know this! Is this true for everyone or only certain documentation generators?

Further, the format differs in that one contains {account} and the other {account_id}. Which format is preferred?

{account}

gajones155 commented 4 years ago

Included whenever --appendFormatStringForFieldSeg=True (it's False by default).

See buildFlatSubpathString in the docgen code for where this is done.