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...
}

}