From d77d21e0db33cb758b8bfe85a5db8fc791c23577 Mon Sep 17 00:00:00 2001 From: Michael Vandeberg Date: Fri, 23 Jan 2026 15:42:31 -0700 Subject: [PATCH] Improve Code Rabbit docs prompt --- .coderabbit.yaml | 33 +++++++++++++++++++++++++-------- 1 file changed, 25 insertions(+), 8 deletions(-) diff --git a/.coderabbit.yaml b/.coderabbit.yaml index f932e884..9ec038ae 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -48,11 +48,28 @@ reviews: - path: "**/*.{cpp,hpp}" instructions: | Documentation Best Practices - - The top of the file after the includes, put a nice /* */ section - which gives a high level overview of how the implementation works. - - Single line // comments are to be used sparingly and judiciously - which explain the why (not the what or how) when it is non-obvious. - - Docstrings are required for all classes in public headers in - non detail namespaces. They are used for generating the Documentation - website. Please give warnings for any class or function that does - not have a docstring or has an insufficient docstring. + - Docstrings are required for all classes and functions in public + headers in non-detail namespaces. Docstrings should include a brief + description of purpose, document all parameters, return values, and + any preconditions, postconditions, or exceptions. For template + parameters, document constraints or concepts required. Warn if a + class or function is missing a docstring or if the docstring fails + to cover these elements. + - Avoid redundant documentation that merely restates the obvious from + the name and signature. Docstrings should add value beyond what the + declaration already communicates. Do not warn about terse + documentation for self-explanatory accessors or trivial type aliases. + - Document thread-safety guarantees and exception specifications where + applicable, particularly for classes intended for concurrent use or + functions that may throw. + - Files containing non-trivial implementation logic should include a + `/* */` block comment after the includes that provides a high-level + overview of how the implementation works. This should highlight + anything tricky or non-obvious that a maintainer might need to know + in order to reason effectively about the code. Warn if such files + lack this overview or if the overview appears stale relative to the + code. + - Single-line `//` comments within code should be used sparingly and + judiciously, explaining the why (not the what or how) when it is + non-obvious. Warn about comments that merely restate what the code + does or excessive commenting that adds noise rather than clarity.