Forbid a trailing // after a one-paragraph proto doc comment

guidelines/documentation.md

@@ -1,8 +1,9 @@
 # Documentation & comments
 
 Language-specific API-documentation conventions live on dedicated pages:
-[Javadoc](javadoc.md) and [KDoc](kdoc.md). English grammar, punctuation,
-and spelling rules — for every language — are catalogued in [English style](english-style.md).
+[Javadoc](javadoc.md), [KDoc](kdoc.md), and [Protobuf](protobuf.md#api-documentation).
+English grammar, punctuation, and spelling rules — for every language — are
+catalogued in [English style](english-style.md).
 
 ## Commenting guidelines
 - Avoid inline comments in production code unless necessary.
@@ -66,10 +67,59 @@ above):
 /** `KoverConfig` feeds the file into Kover. */
 ```
 
-## Protobuf file headers
-- In `.proto` files, a multi-paragraph documentation header must end with a
-  trailing empty comment line (`//`).
-- Single-paragraph headers do not require the trailing empty comment line.
+## Protobuf doc comments
+
+These rules cover every doc comment in a `.proto` file, whatever it
+documents: the file as a whole, a message, a field, a `oneof`, an enum or enum
+value, a service, or an RPC.
+
+- A doc comment of **one paragraph** ends with its last line of text. Do
+  **not** add a trailing empty comment line (`//`) after it.
+- A doc comment of **two or more paragraphs** ends with a trailing empty
+  comment line (`//`) after its last paragraph.
+
+The copyright notice is not a doc comment and keeps its own layout.
+
+Right — no `//` after one paragraph, a `//` after two:
+
+```proto
+// The catch-up has been started.
+message CatchUpStarted {
+
+    CatchUpId id = 1;
+}
+
+// The catch-up has moved to the `FINALIZING` status.
+//
+// The catch-up emits this event for itself.
+//
+message FinalizationStarted {
+
+    CatchUpId id = 1;
+}
+```
+
+Wrong — a `//` after one paragraph, none after two:
+
+```proto
+// The catch-up has been started.
+//
+message CatchUpStarted {
+
+    CatchUpId id = 1;
+}
+
+// The catch-up has moved to the `FINALIZING` status.
+//
+// The catch-up emits this event for itself.
+message FinalizationStarted {
+
+    CatchUpId id = 1;
+}
+```
+
+[Protobuf code style](protobuf.md#api-documentation) states the same rule and
+shows it on messages and fields.
 
 ## Capitalisation in headers
 

guidelines/protobuf.md

@@ -49,8 +49,11 @@ Spine-related imports should follow after an empty line break.
 
 The English in doc comments follows the rules in [English style](english-style.md).
 
-If documentation of a type or a field fits into one paragraph, do NOT add an empty line after
-the paragraph.
+The two rules below hold for every doc comment in a `.proto` file, whatever it documents:
+the file as a whole, a message, a field, a `oneof`, an enum or enum value, a service, or an RPC.
+The copyright notice in the file header is not a doc comment and keeps its own layout.
+
+If a doc comment is a single paragraph, do NOT add an empty comment line (`//`) after it.
 
 ```proto
 // This is how to document a proto type description of which
@@ -62,7 +65,7 @@ message OneParaExample {
 }
 ```
 
-If a field or a message requires two or more paragraphs, the text should end with an empty line.
+If a doc comment has two or more paragraphs, it must end with an empty comment line (`//`).
 
 ```proto
 // Demonstrates how to document API with larger pieces of text.

skills/review-docs/SKILL.md

@@ -24,8 +24,8 @@ The authoritative standards live in `.agents/`:
   diagram at `.agents/guidelines/widow-runt-orphan.jpg`).
 - `.agents/guidelines/english-style.md` — the English grammar, punctuation,
   and spelling catalog, with per-language "Never edit" protections (Check E).
-- `.agents/guidelines/protobuf.md` — Protobuf doc-comment paragraph and
-  blank-line structure (Check A's Protobuf rule).
+- `.agents/guidelines/protobuf.md` — Protobuf doc-comment paragraphs and
+  the trailing empty comment line (Check A's Protobuf rule).
 - `.agents/guidelines/documentation-tasks.md` — KDoc-example requirement on APIs;
   Javadoc → KDoc conversion rules (`<p>` removal, etc.).
 - `.agents/skills/writer/SKILL.md` — Markdown conventions (footnote-style
@@ -40,9 +40,9 @@ The authoritative standards live in `.agents/`:
    `git diff <base>...HEAD` depending on what the user describes. Restrict
    to files matching:
    - `**/*.kt`, `**/*.kts`, `**/*.java` — KDoc/Javadoc inside sources
-   - `**/*.proto` — Protobuf doc comments: type, field, enum, and service
-     docs as well as the file header (a primary API surface, not only the
-     header)
+   - `**/*.proto` — Protobuf doc comments, whatever they document: the file
+     as a whole, a message, a field, a `oneof`, an enum or enum value, a
+     service, or an RPC (a primary API surface)
    - `**/*.ts`, `**/*.tsx`, `**/*.js`, `**/*.jsx`, `**/*.mjs`, `**/*.cjs` —
      TSDoc/JSDoc and other comments, in repos that have them
    - `**/*.go` — Go doc comments and other comments, in repos that have them
@@ -118,10 +118,15 @@ those languages review the prose (C/D/E) and leave their structure alone.
   unit and resolves fine — do not flag it. Fix: demote to a code span
   (`` `KoverConfig` ``). See the "No doc links to `buildSrc` / `config` types"
   section of `.agents/guidelines/documentation.md`.
-- **Multi-paragraph Protobuf doc comments end with an empty comment line.**
-  Per `.agents/guidelines/protobuf.md` § API documentation, any `.proto` file
-  header, message, or field doc comment spanning two or more paragraphs must
-  end with a trailing empty comment line (`//`).
+- **A Protobuf doc comment ends with `//` if, and only if, it has two or
+  more paragraphs.** Per `.agents/guidelines/protobuf.md` § API
+  documentation, this holds for every `.proto` doc comment, whatever it
+  documents: the file as a whole, a message, a field, a `oneof`, an enum or
+  enum value, a service, or an RPC. A doc comment of two or more
+  paragraphs must end with a trailing empty comment line (`//`); a
+  one-paragraph doc comment must not. Either mistake is a Should-fix: a
+  trailing `//` after a single paragraph, or none after the last of several.
+  The copyright notice is not a doc comment; leave its layout alone.
 - **Line length.** KDoc / Javadoc body lines wrap at the limit from
   `.agents/guidelines/coding.md` frontmatter (`max-line-length`), applied to
   changed lines only. Long body lines are **Should fix**; code lines around
@@ -206,6 +211,7 @@ Three sections, in this order:
   (`<p>` tags) left in Kotlin KDoc, broken Markdown links, and
   meaning-distorting English errors (Check E).
 - **Should fix** — TODO format, inline-comment overuse in production,
+  an unwanted or missing trailing `//` in a Protobuf doc comment (Check A),
   inline external links that should be footnote-style, missing typographic
   quotes (or unwanted ones), widow/runt/orphan/river paragraphs,
   fenced-vs-indented code blocks, KDoc/Javadoc body or Markdown lines