Documentation Generator Skill

This skill generates XML documentation comments for C# code that lacks them.

Tool Location: D:\FractalDataworks\RoslynTools\src\RoslynTools.DocGenerator

When to Use This Skill

• User explicitly requests: "Add XML documentation"
• Generating public API documentation
• After code-writer creates code without docs
• Preparing code for NuGet package
• During API review
• When user wants IntelliSense descriptions

When NOT to Use This Skill

• During code analysis (use code-reader to strip docs instead)
• For internal/private code (unless requested)
• When docs already exist and are good
• For trivial getters/setters

API Endpoint

POST /generation/documentation

Request:

{
  "scope": "type",
  "target": "MyNamespace.MyClass",
  "inferFromNames": true,
  "includeRemarks": false
}

Response:

{
  "isSuccess": true,
  "data": {
    "documentation": [
      {
        "memberName": "GetById",
        "xmlDoc": "/// <summary>\n/// Retrieves a product by its unique identifier\n/// </summary>\n/// <param name=\"id\">The product identifier</param>\n/// <returns>Result containing the product</returns>"
      }
    ]
  }
}

How It Works

1. Start the Server

dotnet run --project D:\FractalDataworks\RoslynTools\src\CyberdineDevelopment.RoslynTools.Server

2. Load Solution

using CyberdineDevelopment.RoslynTools.Client;

var client = new RoslynWorkspaceClient("http://localhost:5000");
await client.LoadSolution(@"D:\MyProject\MyProject.sln");

3. Generate Documentation

// Generate docs for a type
var result = await client.GenerateDocumentation(
    scope: "type",
    target: "MyNamespace.ProductService",
    inferFromNames: true
);

if (result.IsSuccess)
{
    foreach (var doc in result.Data.Documentation)
    {
        Console.WriteLine($"Member: {doc.MemberName}");
        Console.WriteLine(doc.XmlDoc);
    }
}

Semantic Analysis Benefits

Using the Server API provides significant advantages:

• Full Type Information: Access to ISymbol for accurate parameter and return type documentation
• Inheritance Awareness: Can document inherited members correctly
• Generic Type Support: Properly document generic types with constraints
• Cross-Reference: Generate accurate <see cref="..."/> tags
• Interface Mapping: Know which members implement interface members
• Better Inference: Use semantic model to infer better documentation from code context

What This Skill Does

Generates XML docs by analyzing:

1. Method signatures → Summary, params, returns
2. Naming conventions → Infer purpose from names
3. Parameter types → Describe what they represent
4. Return types → Describe what's returned
5. Code structure → Understand behavior

Example Output

Before:

public IGenericResult<Product> GetById(int id)
{
    return _repository.GetById(id);
}

After:

/// <summary>
/// Retrieves a product from the repository by its unique identifier
/// </summary>
/// <param name="id">The unique identifier of the product to retrieve</param>
/// <returns>
/// An <see cref="IGenericResult{Product}"/> containing the product if found,
/// or an error result if the product does not exist
/// </returns>
public IGenericResult<Product> GetById(int id)
{
    return _repository.GetById(id);
}

Documentation Patterns

Methods

/// <summary>
/// [Verb] [what] [optional: from where/to where]
/// </summary>
/// <param name="paramName">Description of parameter</param>
/// <returns>Description of return value</returns>

Verbs by pattern:

• Get* → "Gets" or "Retrieves"
• Create* → "Creates"
• Update* → "Updates"
• Delete* → "Deletes"
• Validate* → "Validates"
• Calculate* → "Calculates"
• Process* → "Processes"

Properties

/// <summary>
/// Gets or sets the name of the product
/// </summary>
public string Name { get; set; }

Classes

/// <summary>
/// Service for managing product-related operations
/// </summary>
public class ProductService

Smart Generation Features

1. Type Inference

public User GetUser(int userId)

// Generated:
/// <summary>
/// Gets the user by their unique identifier
/// </summary>
/// <param name="userId">The unique identifier of the user</param>
/// <returns>The user with the specified identifier</returns>

2. Result Pattern Recognition

public IGenericResult<Product> Create(ProductDto dto)

// Generated:
/// <summary>
/// Creates a new product from the provided data transfer object
/// </summary>
/// <param name="dto">The product data transfer object</param>
/// <returns>
/// Result containing the created product if successful,
/// or error information if creation failed
/// </returns>

3. Boolean Methods

public bool Exists(int id)

// Generated:
/// <summary>
/// Determines whether a product with the specified identifier exists
/// </summary>
/// <param name="id">The product identifier to check</param>
/// <returns>
/// <c>true</c> if a product with the specified identifier exists;
/// otherwise, <c>false</c>
/// </returns>

Documentation Rules

DO Document:

✅ Public classes, interfaces, enums ✅ Public methods and properties ✅ Protected members (for extensibility) ✅ Parameters and return values

DON'T Document (unless requested):

❌ Private methods (implementation details) ❌ Auto-properties with obvious names ❌ Simple getters/setters ❌ Test methods (tests are self-documenting)

Special Cases:

Override methods:

/// <inheritdoc/>
public override string ToString()

Workflow

When this skill is invoked:

1. Determine target file to document
2. Run the DocGenerator tool
3. Review generated documentation
4. Write updated file with docs

Integration with Other Skills

With code-writer

code-writer (no docs) → Write file → doc-generator → Add docs

Benefit: Minimal context during generation, docs added after

Example Usage

User asks:

• "Add XML documentation to ProductService.cs"
• "Generate docs for this API"

Skill will:

1. Run DocGenerator on the file
2. Add XML documentation comments
3. Update the file

Notes

• Non-destructive: Preserves existing good docs
• Smart: Uses semantic model to understand patterns and conventions
• Fast: In-memory generation
• Accurate: Based on actual compilation with full type information
• Optional: Only when requested or needed
• Cross-Reference Ready: Generates proper <see cref=""/> tags with semantic validation
• Server State: Can generate docs for edited files before committing to disk