Documentation

Documentation Workflow

When to Use This Skill

• Creating API documentation
• Writing code comments
• Updating README files
• Generating architecture documentation

Documentation Types

1. Code Comments

• XML docs for public APIs
• Inline comments for complex logic
• TODO/FIXME for technical debt

2. API Documentation

• Endpoint descriptions
• Request/response schemas
• Error codes and handling

3. Architecture Documentation

• Component diagrams
• Data flow documentation
• Integration guides

Pattern 1: C# XML Documentation

/// <summary>
/// Saves or updates an employee entity.
/// </summary>
/// <remarks>
/// This command handles both create and update operations.
/// For new employees, the Id should be null or empty.
/// </remarks>
/// <example>
/// <code>
/// var command = new SaveEmployeeCommand
/// {
///     Name = "John Doe",
///     Email = "john@example.com"
/// };
/// var result = await handler.HandleAsync(command, cancellationToken);
/// </code>
/// </example>
public sealed class SaveEmployeeCommand : PlatformCqrsCommand<SaveEmployeeCommandResult>
{
    /// <summary>
    /// The unique identifier of the employee.
    /// Null or empty for new employees.
    /// </summary>
    public string? Id { get; set; }

    /// <summary>
    /// The employee's full name.
    /// </summary>
    /// <value>Must be non-empty and max 200 characters.</value>
    public string Name { get; set; } = string.Empty;
}

/// <summary>
/// Represents a unique expression for finding an employee.
/// </summary>
/// <param name="companyId">The company identifier.</param>
/// <param name="userId">The user identifier.</param>
/// <returns>An expression that matches the unique employee.</returns>
public static Expression<Func<Employee, bool>> UniqueExpr(string companyId, string userId)
    => e => e.CompanyId == companyId && e.UserId == userId;

Pattern 2: TypeScript JSDoc

/**
 * Manages the feature list state and operations.
 *
 * @example
 * ```typescript
 * @Component({
 *   providers: [FeatureListStore]
 * })
 * export class FeatureListComponent {
 *   constructor(private store: FeatureListStore) {
 *     store.loadItems();
 *   }
 * }
 * ```
 */
@Injectable()
export class FeatureListStore extends PlatformVmStore<FeatureListState> {
  /**
   * Loads items from the API with current filters.
   *
   * @remarks
   * This effect automatically tracks loading state under the key 'loadItems'.
   * Use `isLoading$('loadItems')` to check loading status.
   *
   * @see {@link FeatureApiService.getList}
   */
  public loadItems = this.effectSimple(() => /* ... */);

  /**
   * Updates the filter criteria and resets to first page.
   *
   * @param filters - Partial filter object to merge with current filters
   *
   * @example
   * ```typescript
   * // Filter by status
   * store.setFilters({ status: FeatureStatus.Active });
   *
   * // Filter by search text
   * store.setFilters({ searchText: 'keyword' });
   * ```
   */
  public setFilters(filters: Partial<FeatureFilters>): void {
    // ...
  }
}

/**
 * Represents a feature entity from the API.
 */
export interface FeatureDto {
  /** Unique identifier */
  id: string;

  /** Display name of the feature */
  name: string;

  /**
   * Current status of the feature.
   * @default FeatureStatus.Draft
   */
  status: FeatureStatus;
}

Pattern 3: API Endpoint Documentation

/// <summary>
/// Employee management endpoints.
/// </summary>
[ApiController]
[Route("api/[controller]")]
[PlatformAuthorize]
public class EmployeeController : PlatformBaseController
{
    /// <summary>
    /// Retrieves a paginated list of employees.
    /// </summary>
    /// <param name="query">Query parameters for filtering and pagination.</param>
    /// <returns>Paginated list of employees.</returns>
    /// <response code="200">Returns the employee list.</response>
    /// <response code="400">Invalid query parameters.</response>
    /// <response code="401">Unauthorized - authentication required.</response>
    /// <response code="403">Forbidden - insufficient permissions.</response>
    [HttpGet]
    [ProducesResponseType(typeof(GetEmployeeListQueryResult), StatusCodes.Status200OK)]
    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
    public async Task<IActionResult> GetList([FromQuery] GetEmployeeListQuery query)
        => Ok(await Cqrs.SendAsync(query));

    /// <summary>
    /// Creates or updates an employee.
    /// </summary>
    /// <param name="command">Employee data to save.</param>
    /// <returns>The saved employee.</returns>
    /// <response code="200">Employee saved successfully.</response>
    /// <response code="400">Validation failed.</response>
    /// <response code="404">Employee not found (for updates).</response>
    [HttpPost]
    [ProducesResponseType(typeof(SaveEmployeeCommandResult), StatusCodes.Status200OK)]
    [ProducesResponseType(typeof(ValidationProblemDetails), StatusCodes.Status400BadRequest)]
    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
    public async Task<IActionResult> Save([FromBody] SaveEmployeeCommand command)
        => Ok(await Cqrs.SendAsync(command));
}

Pattern 4: README Documentation

# Feature Name

Brief description of what this feature does.

## Overview

More detailed explanation of the feature's purpose and functionality.

## Architecture

┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ Frontend │────▶│ API Layer │────▶│ Domain Layer │ │ Component │ │ Controller │ │ Entity │ └─────────────────┘ └──────────────────┘ └─────────────────┘

## Usage

### Backend

```csharp
// Example usage
var command = new SaveFeatureCommand { Name = "Example" };
var result = await handler.HandleAsync(command, cancellationToken);

Frontend

// Example usage
this.store.loadItems();

Configuration

API Endpoints

Error Handling

Related

• Entity Documentation
• API Reference

## Pattern 5: Inline Code Comments

```csharp
protected override async Task<SaveEmployeeCommandResult> HandleAsync(
    SaveEmployeeCommand request, CancellationToken cancellationToken)
{
    // Step 1: Determine if this is a create or update operation
    var isCreate = request.Id.IsNullOrEmpty();

    // Step 2: Get or create the entity
    var employee = isCreate
        ? request.MapToNewEntity()
            .With(e => e.CreatedBy = RequestContext.UserId())
        : await repository.GetByIdAsync(request.Id, cancellationToken)
            .EnsureFound($"Employee not found: {request.Id}")
            .Then(existing => request.UpdateEntity(existing));

    // Step 3: Validate business rules
    // NOTE: This checks for duplicate codes within the same company
    await employee.ValidateAsync(repository, cancellationToken).EnsureValidAsync();

    // Step 4: Persist changes
    // The repository automatically raises entity events for cross-service sync
    var saved = await repository.CreateOrUpdateAsync(employee, cancellationToken);

    // Step 5: Return result
    return new SaveEmployeeCommandResult
    {
        Employee = new EmployeeDto(saved)
    };
}

Documentation Guidelines

DO

• Document public APIs with XML/JSDoc
• Explain "why" not "what"
• Include usage examples
• Keep documentation close to code
• Update docs when code changes

DON'T

• State the obvious
• Leave TODO comments indefinitely
• Write documentation that duplicates code
• Create separate docs that become stale

Comment Types

Verification Checklist

• Public APIs have XML/JSDoc documentation
• Complex logic has explanatory comments
• Examples are provided where helpful
• Documentation is accurate and up-to-date
• No obvious/redundant comments
• TODO/FIXME items are actionable