From c3bce96d75425215143d253ab73949ebe0e99265 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Recep=20=C5=9Een?= Date: Sat, 10 Oct 2026 15:18:13 +0300 Subject: [PATCH] docs: align xml documentation and code comment policy AGENTS.md said no docstrings or comments while CONTRIBUTING.md asked for XML documentation on public APIs. XML documentation comments on public APIs are now expected everywhere; inline code comments that explain code remain disallowed. No code or behaviour change. Refs #146 Co-Authored-By: Claude Sonnet 5.5 --- .claude/rules/csharp.md | 1 + .kimi/skills/csharp-conventions/SKILL.md | 1 + AGENTS.md | 2 +- CONTRIBUTING.md | 4 ++-- 4 files changed, 5 insertions(+), 3 deletions(-) diff --git a/.claude/rules/csharp.md b/.claude/rules/csharp.md index 6cd5b2e..a06e90a 100644 --- a/.claude/rules/csharp.md +++ b/.claude/rules/csharp.md @@ -14,3 +14,4 @@ paths: ["**/*.cs"] - Functional types (Result, Maybe, Any) use implicit operators for ergonomic construction — maintain this pattern in new types. - Record types are preferred over classes for immutable value objects. - `TreatWarningsAsErrors=true` is global — never suppress a warning without understanding why it fires. +- XML documentation comments (`///`) on public APIs are expected. No inline code comments (`//`, `/* */`) that explain code. diff --git a/.kimi/skills/csharp-conventions/SKILL.md b/.kimi/skills/csharp-conventions/SKILL.md index d96b18c..c0ca3c9 100644 --- a/.kimi/skills/csharp-conventions/SKILL.md +++ b/.kimi/skills/csharp-conventions/SKILL.md @@ -15,3 +15,4 @@ description: C# coding conventions for CSharpEssentials. Use when writing, revie - Functional types (Result, Maybe, Any) use implicit operators for ergonomic construction; maintain this pattern in new types. - Record types are preferred over classes for immutable value objects. - `TreatWarningsAsErrors=true` is global; never suppress a warning without understanding why it fires. +- XML documentation comments (`///`) on public APIs are expected. No inline code comments (`//`, `/* */`) that explain code. diff --git a/AGENTS.md b/AGENTS.md index a9f771b..fcb6a48 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -45,7 +45,7 @@ Releases are automated with [release-please](https://github.com/googleapis/relea - Don't add `// TODO` to committed code — either implement it or track it as an issue. - Don't add new packages to `Directory.Packages.props` without checking existing entries. - Don't break multi-targeting — test against all declared target frameworks. -- Don't add docstrings or comments unless explicitly asked. +- Don't add inline code comments (`//`, `/* */`) that explain code unless explicitly asked. XML documentation comments (`///`) on public APIs are expected. - Don't create placeholder/stub implementations. ## Boundaries diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 860a28c..e48a1ec 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -154,7 +154,7 @@ We use GitHub issues to track public bugs. Report a bug by [opening a new issue] - Use 4 spaces for indentation - Follow C# coding conventions -- Write XML documentation for public APIs +- Write XML documentation for public APIs; do not add inline code comments that explain code - Keep methods small and focused - Use meaningful names for variables and methods @@ -168,7 +168,7 @@ We use GitHub issues to track public bugs. Report a bug by [opening a new issue] ## Documentation - Update relevant documentation -- Include XML comments for public APIs +- Include XML documentation comments (`///`) for public APIs - Update README.MD if needed (package table, badges) - Update the package `Readme.MD` and the matching `.well-known/agent-skills//SKILL.md` when a public API changes - Do not bump the version or edit `CHANGELOG.md` in a feature pull request; release-please generates both