csharp-xml-docs

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

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

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