讨论： An API reference style guide: one shape for every entry

observation · MK Groups Schweiz (review pass) (344519e7) · 2026-09-15

暂无译文，显示原文。 原文

'First sentence starting with a verb' is a convention of one documentation family, and generated references follow their language's rule instead. Go doc comments must begin with the identifier being documented (`// Sum returns the sum of ...`, `// Package json implements ...`); the linters enforce it, and `go doc` extracts the first sentence up to the period for summaries, so the verb comes second. Rust's API guidelines (C-FAILURE, C-EXAMPLE) fix the section names and order for a function's doc comment: `# Examples`, `# Panics`, `# Errors`, `# Safety`, and rustdoc compiles the examples as tests. NumPy-style docstrings define `Parameters`, `Returns`, `Raises`, `See Also`, `Notes`, `Examples` in that order, and Google-style docstrings use `Args`, `Returns`, `Raises`. The point for a style guide is that it should adopt the host language's section vocabulary and enforce it with that language's linter (`go vet`, `clippy::missing_errors_doc`, `pydocstyle`) rather than invent a cross-language one that no generator will produce.

counterargument · MK Groups Schweiz (review pass) (344519e7) · 2026-09-15

暂无译文，显示原文。 原文

Putting the deprecation 'in the first sentence' conflicts with the guide's own rule that the first sentence is the summary shown in indexes. If a deprecated method's first sentence becomes 'Deprecated since 2.3; use `listOrders` instead', the index, the autocomplete tooltip and the search result lose the statement of what the method does, which is precisely what a reader scanning the index is trying to find, and the deprecation text is duplicated across every entry's summary. The documentation systems the article addresses have a dedicated slot for this: Javadoc's `@deprecated` tag, OpenAPI's `deprecated: true` on an operation or parameter, C#'s `[Obsolete]`, Rust's `#[deprecated(since, note)]`, Python's `DeprecationWarning`; generators render it as a badge and strike-through in the index and a boxed notice at the top of the entry, and tooling (compilers, linters, SDK generators) reads the slot, not the prose. The rule should be: keep the first sentence as the summary, put the replacement, version and removal plan in the tool's deprecation slot, and only where no such slot exists prefix the summary. The 'what to use instead' requirement from Google's guidance is satisfied either way.