# Aspid Mvvm Xmldoc > Conventions for writing XML documentation comments (`///`) in the Aspid.MVVM C# framework — `

`, ``, ``, ``, ``, ``, ``, hook methods, binder `` includes, and class hierarchy-style summaries. Use this skill whenever writing, editing, or reviewing XML doc comments on classes, interfaces, methods, properties, events, binders, or attributes anywhere in the Aspid.MVVM repo, or when the user asks how to document something in this project, to add XML docs to a file, to write a summary for a binder, to format a `` or `` block, or to fix inconsistent/missing documentation. Also triggers on phrases like "document this", "add XML docs", "write a summary for", "fix the docs on", "document the binder", or when editing `.cs` files that already contain `///` blocks. Use when this capability is needed. - Skill: `tomevault-io/aspid-mvvm-xmldoc` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/aspid-mvvm-xmldoc` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/aspid-mvvm-xmldoc/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/aspid-mvvm-xmldoc --- # Aspid.MVVM XML Documentation Conventions Rules for XML doc comments on all public and protected APIs in the Aspid.MVVM framework. The point of these conventions is consistency: every class summary reads in the same hierarchy style, every `` uses the same phrasing, every nullable return and keyword is rendered with ``. Readers (and IDE tooltips) rely on that consistency. Skim the quick rules below first — they cover ~80% of cases. For deeper topics (class summaries, hook methods, binder examples), consult the matching reference file. ## When to use reference files - **Writing a class/struct/interface `

`** → read `references/class-summary.md` (hierarchy-style templates for abstract, sealed, concrete, and binder-targeting-specific-properties cases). - **Documenting hook methods, ``, ``, `` for Unity conditional behavior, `[Tooltip]` rules** → read `references/tags.md`. - **Writing `` blocks for non-MonoBehaviour binder classes** (using `XmlExampleDoc-*.xml` files and ``) → read `references/binders.md`. Note: `MonoBinder` classes (MonoBehaviour-based) do NOT need `` or XML example blocks. --- ## Properties | Access | Format | |---|---| | Get-only | `Gets the X.` | | Get + set | `Gets or sets the X.` | | Boolean state | `Indicates whether X.` | Add a second sentence for non-obvious defaults. Use `` / `` — never `true`. --- ## Events Pattern: `"Raised when X."` or `"Raised with X when Y."` --- ## `` | Role | Format | |---|---| | Action/callback | `The action invoked with the converted value.` | | Binding mode | `The binding mode. [constraints]` | | Target object | `The X to bind.` | | Boolean flag | `When , [effect].` | | Converter | `The converter used to transform X to Y.` | | Nullable optional | `The X, or to use the default.` | | Enum value (binder) | `The bound enum value received from the ViewModel.` | | Element | `The target element.` | --- ## `` State *what kind of type* is expected — not just `"The type."`: ```csharp /// The type of that exposes the target property. /// The runtime type of the incoming value. ``` --- ## `` Describe both success and fallback cases: - `The binder instance if found; otherwise, .` - ` if the binding was established; otherwise, .` --- ## Null references and keywords Always use `` — never `...` — for: `null`, `true`, `false`, `this`, `void`, `default`, `new`. The reason is semantic: `` tells the doc renderer these are language keywords, which enables proper styling and cross-language rendering. `` is plain monospace formatting and loses that signal. --- ## Enum values Always `` — never `EnumValue`. Use `label` when the member name alone is unclear to the reader. --- ## Method references in `` Include parameter types when referencing a specific overload so the link resolves unambiguously: ``` ``` --- ## Static / extension method classes - Extension methods: `"Provides extension methods for instances that implement ."` - Utility: `"Provides utility methods for ."` --- ## Summary formatting Always use multiline form; always end with a period. Never use the single-line `///

` form — it's harder to extend later and inconsistent with the rest of the codebase. --- ## Quick reference checklist Before finishing a file with XML docs, verify: - [ ] Class summary follows hierarchy style (see `references/class-summary.md`) - [ ] Non-MonoBehaviour binders have `` blocks via `` from `XmlExampleDoc-*.xml` (see `references/binders.md`) - [ ] MonoBinder (MonoBehaviour) classes do NOT have `` / `` blocks - [ ] Constructors: `` when matching parent; full doc when API differs (see `references/tags.md`) - [ ] No `` where behavior differs from base - [ ] `` / `` — never `null` / `true` - [ ] Enum members: `` — never `EnumValue` - [ ] Every `[SerializeField]` / `[SerializeReference]` has `[Tooltip]` - [ ] `` does not duplicate `` / `` content - [ ] Exception docs cover Unity conditional behavior (skip / log / throw — see `references/tags.md`) - [ ] `` is concrete — not just `"The type."` - [ ] Properties: `"Gets"`, `"Gets or sets"`, `"Indicates whether"` - [ ] Events: `"Raised when X."` or `"Raised with X when Y."` - [ ] Virtual hooks: `"Called [when]. Override to [purpose]."` (see `references/tags.md`) - [ ] Overrides requiring `base.Method()` have a `` note - [ ] Summary is multiline and ends with a period --- > Source: [VPDPersonal/Aspid.MVVM](https://github.com/VPDPersonal/Aspid.MVVM) — distributed by [TomeVault](https://tomevault.io).