csharp-xml-docs

Files (18)

• SKILL.md
• best-practices.md · references/
• 01-keep-it-simple.md · references/examples/
• 02-add-context.md · references/examples/
• 03-language-choice.md · references/examples/
• 04-consistency.md · references/examples/
• 05-avoid-redundancy.md · references/examples/
• 06-structured-xml.md · references/examples/
• 07-special-cases.md · references/examples/
• 08-exceptions.md · references/examples/
• 09-enums.md · references/examples/
• 10-extension-methods.md · references/examples/
• 11-property-side-effects.md · references/examples/
• 12-interface-implementation.md · references/examples/
• README.md · references/examples/
• formatting-guidelines.md · references/
• pattern-library.md · references/
• xml-workflow.md · references/

SKILL.md (first lines)

# C# XML Documentation Guide

Comprehensive XML documentation standards for Unity C# projects with flexible language choice.

## Overview

**Foundation Required**: `csharp-code-style` (mPascalCase, Async 접미사 금지, var 금지)

**Core Principle**: XML documentation samples with flexible language choice
- All XML comments (`<summary>`, `<remarks>`, etc.) can be written in Korean or English
- Provides universal reference for documentation standards
- Choose the language that best serves your team and project needs

## Quick Start

```csharp
public class ActionResult
{
    // Simple property - English
    /// <summary>
    /// Indicates whether the action executed successfully
    /// </summary>
    public bool Success { get; set; }

    // Simple property - Korean
    /// <summary>
    /// 액션 실행 성공 여부
    /// </summary>
    public bool Success { get; set; }

    // Complex concept with remarks
    /// <summary>
    /// Indicates whether the action was skipped
    /// </summary>
    /// <remarks>
    /// Set to true when skipped due to unmet conditions.
    /// If true, the action was not executed regardless of Success value.
    /// </remarks>
    public bool Skipped { get; set; }
}
```

## Language Choice Guidelines

### Acceptable Options

1. **Pure Korean** (한글 전용)
2. **Pure English** (영문 전용)
3. **Mixed Korean + English** (혼용)

### Context-Based Recommendations

| Context | Recommended Language | Rationale |
|---------|---------------------|-----------|
| Internal team project | Korean or Team preference | Maximum clarity for team members |
| Open source / International | English or Mixed | Broader accessibility |
| Company standard exists | Follow company policy | Consistency across projects |
| Mixed team | English or Both | Accommodate all members |
| Legacy codebase | Match existing style | Maintain consistency |

### Consistency Rules

**Within a single file:**
- Consistent: All Korean OR All English OR All Mixed
- Inconsistent: Random switching between languages

**Across the project:**
- Maintain similar language strategy across similar components
- Document language choice in project README or CLAUDE.md
- Use consistent language for related interfaces and implementations

## Quick Decision Matrix

| Scenario | Summary | Remarks | Additional Tags | Example |
|----------|---------|---------|-----------------|---------|
| Simple property | Yes | No | No | `bool Success` |
| Complex concept | Yes | Yes | No | `bool Skipped` with conditions |
| Property with side effects | Yes | Optional | `<value>` | `CurrentMode` |
| Public class/struct | Yes | Yes | No | `class ActionResult` |
| Factory method | Yes | Only if special case | No | `CreateSuccess()` |
| Method with exceptions | Yes | Optional | `<exception>` per exception | `LoadVRM()` |
| Internal method | Optional | No | No | `initializeDefaults()` |
| Enum type | Yes | Optional | No | `EAnimationMode` |
| Enum values | Yes (each) | No | No | `VRMAnimation`, `AnimatorController` |
| Extension method | Yes | Optional | Document `this` param | `ActivateWithConfigAsset()` |
| Interface method | Yes (full) | Yes | All applicable | `IActionHandler.Execute()` |
| Implementation method | `<inheritdoc/>` | Implementation details only | Override if needed | `PlayerPrefsActionHandler.Execute()` |

## On-Demand Documentation Workflow

**Critical Principle**: XML documentation is **NOT auto-applied**. Only generated when explicitly requested.

### 3-Step Review Process

1. **Claude-Haiku (Draft Generation)**
   - Fast, efficient initial documentation draft
   - Follows established patterns from Pattern Library
   - Sets foundation for review

2. **Gemini or Codex CLI (Expert Review)**
   - Professional review and refinement
   - Cross-validates patterns and consistency
   - Improves clarity and completeness

3. **Final Approval**
   - Manual confirmation of reviewed documentation
   - Integration into codebase

See **[XML Documentation Workflow](references/xml-workflow.md)** for detailed process.

## Reference Documentation

### [Pattern Library](references/pattern-library.md)
Complete examples for all common scenarios:
- Simple properties and fields
- Complex concepts requiring remarks
- Classes and structs
- Methods (simple, complex, multi-step)
- Factory methods

From viniciuscs84/sdd-toolkit, MIT.

More from viniciuscs84/sdd-toolkit