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

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

Pure Korean (한글 전용)
Pure English (영문 전용)
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

Claude-Haiku (Draft Generation)
- Fast, efficient initial documentation draft
- Follows established patterns from Pattern Library
- Sets foundation for review
Gemini or Codex CLI (Expert Review)
- Professional review and refinement
- Cross-validates patterns and consistency
- Improves clarity and completeness
Final Approval
- Manual confirmation of reviewed documentation
- Integration into codebase

See XML Documentation Workflow for detailed process.

Reference Documentation

Pattern Library

Complete examples for all common scenarios:

Simple properties and fields
Complex concepts requiring remarks
Classes and structs
Methods (simple, complex, multi-step)
Factory methods
Enums and bit flags
Exception documentation
Extension methods
Interface vs Implementation patterns

Formatting Guidelines

When to use various XML tags:

<br/> vs <list> for structured content
<value> for properties with side effects
<exception> for documented exceptions
<para> for multi-paragraph remarks

Best Practices

Essential principles for effective documentation:

Keep it simple for straightforward elements
Add context where needed
Be consistent with language choice
Avoid redundancy
Document special cases

XML Documentation Workflow

3-step documentation process using Claude-Haiku, Gemini/Codex review, and final approval

Critical Pattern: Interface vs Implementation

Interface: Full Documentation

/// <summary>
/// Interface dedicated to VTuber Animation control (ISP compliance)
/// </summary>
/// <remarks>
/// Interface for clients that only control animation playback.<br/>
/// State Query and Observable features are separated into distinct interfaces.
/// </remarks>
public interface IVTuberAnimationController
{
    /// <summary>
    /// Plays animation asynchronously
    /// </summary>
    /// <param name="animationPath">Animation path</param>
    /// <param name="wrapMode">Playback mode (Loop/Once/PingPong)</param>
    /// <returns>
    /// true: Playback start succeeded<br/>
    /// false: Playback start failed
    /// </returns>
    /// <remarks>
    /// <strong>Preconditions:</strong><br/>
    /// - Context must be ready (IsReady = true)<br/>
    /// - animationPath must not be null
    /// </remarks>
    UniTask<bool> PlayAnimation(string animationPath, WrapMode wrapMode);
}

Implementation: Use <inheritdoc/> + Implementation Details

public partial class VRMController : IVTuberAnimationController
{
    private IAnimationSystem mCurrentSystem;
    private readonly Dictionary<string, Animation> mAnimations;

    /// <inheritdoc/>
    /// <remarks>
    /// <strong>Implementation:</strong> Path prefix-based auto-routing ("VRMA/" -> VRMAnimation, "State/{Layer}/{Identifier}" -> AnimatorController)<br/>
    /// <strong>Main Failures:</strong> Unknown prefix, System activation failure, invalid Layer/Identifier<br/>
    /// <strong>Note:</strong> wrapMode ignored when using AnimatorController
    /// </remarks>
    public async UniTask<bool> PlayAnimation(string animationPath, WrapMode wrapMode)
    {
        Debug.Assert(animationPath != null);
        // Implementation...
    }
}

Key Principles

On-Demand Only: XML documentation is NEVER auto-applied. Only generate when explicitly requested
Keep it simple: Concise summaries for straightforward elements
Add context where needed: Complex concepts deserve detailed explanations in remarks
Think about your audience: Choose language (Korean/English/Mixed) that serves your team best
Be consistent: Follow established patterns and use consistent language throughout
Dual-Review Process: Claude-Haiku draft → Expert Review (Gemini/Codex) → Final Approval
Interface vs Implementation: Full docs in interface, <inheritdoc/> + implementation specifics in class
Document exceptions: Use <exception> for exceptions that are part of the method's contract
Property side effects: Use <value> tag when getter/setter have non-obvious behavior
POCU Naming: Use mPascalCase for private fields, camelCase for private methods

IDE Experience

IntelliSense Display:

Simple Property:

Success (bool)
Indicates whether the action executed successfully

Complex Property with Remarks:

Skipped (bool)
Indicates whether the action was skipped

[Show more...] <- Click to expand remarks

Common Examples

Simple Property:

/// <summary>Number of retry attempts</summary>
public int RetryCount { get; set; }

Method with Parameters (POCU Style):

public class DataService
{
    private readonly Dictionary<string, object> mOutputData;

    /// <summary>
    /// Retrieves output data
    /// </summary>
    /// <typeparam name="T">Data type to return</typeparam>
    /// <param name="key">Key to retrieve</param>
    /// <param name="defaultValue">Default value if key not found</param>
    /// <returns>Retrieved data or default value</returns>
    public T GetOutputData<T>(string key, T defaultValue = default(T))
    {
        Debug.Assert(key != null);

        object value;
        if (mOutputData == null || !mOutputData.TryGetValue(key, out value))
        {
            return defaultValue;
        }

        return convertValue<T>(value, defaultValue);
    }

    private T convertValue<T>(object value, T defaultValue)
    {
        try
        {
            if (value is T directValue)
            {
                return directValue;
            }

            return (T)Convert.ChangeType(value, typeof(T));
        }
        catch
        {
            return defaultValue;
        }
    }
}

Multi-Step Process:

public class EventExecutor
{
    private readonly IEventRepository mRepository;
    private readonly IActionProcessor mProcessor;

    /// <summary>
    /// Executes event
    /// </summary>
    /// <remarks>
    /// <para>
    /// <strong>Execution Process:</strong><br/>
    /// 1. Event definition lookup<br/>
    /// 2. Event-level condition evaluation<br/>
    /// 3. Direct action list processing<br/>
    /// 4. Execution time and metadata configuration
    /// </para>
    /// </remarks>
    public async UniTask<EventActionResult> ExecuteEvent(
        string systemId, string eventId, object contextDataOrNull = null)
    {
        Debug.Assert(systemId != null);
        Debug.Assert(eventId != null);

        EventDefinition definition = await mRepository.GetDefinition(systemId, eventId);
        return await processEvent(definition, contextDataOrNull);
    }

    private async UniTask<EventActionResult> processEvent(
        EventDefinition definition, object contextDataOrNull)
    {
        Debug.Assert(definition != null);
        // Implementation...
    }
}