Doc Writer

Documentation Writer Skill

This skill provides guidelines for AI coding agents to help maintainers produce accurate and easy-to-maintain documentation for the Moq.AutoMocker project. The docs/ folder contains the official documentation, and this skill helps ensure consistent, high-quality documentation.

Documentation Overview

Repository Structure

Location: docs/ Audience: .NET developers using Moq.AutoMocker for unit testing Format: Markdown files API Reference: Auto-generated from XML doc comments (do not edit manually)

Documentation Categories

docs/
├── Moq.AutoMock.md                      # Assembly overview (auto-generated)
├── PackageValidation.md                 # Package validation guide
├── SourceGenerators.md                  # Source generators overview
├── Moq.AutoMock/                        # API reference (auto-generated)
│   ├── AutoMocker.md
│   ├── AutoMocker/                      # AutoMocker member docs
│   ├── MockExtensions.md
│   ├── MockExtensions/
│   ├── ObjectGraphContext.md
│   └── ObjectGraphContext/
├── Moq.AutoMock.Resolvers/             # Resolver API reference (auto-generated)
│   ├── IMockResolver.md
│   ├── MockResolver.md
│   ├── LazyResolver.md
│   ├── EnumerableResolver.md
│   └── ...
└── SourceGenerators/                    # Hand-written generator docs
    ├── UnitTestGenerator.md
    ├── OptionsExtensionGenerator.md
    ├── FakeLoggingExtensionGenerator.md
    ├── ApplicationInsightsExtensionGenerator.md
    └── KeyedServicesExtensionGenerator.md

What NOT to Edit

Files in docs/Moq.AutoMock/ and docs/Moq.AutoMock.Resolvers/ are auto-generated from XML doc comments by xmldocmd. They contain the marker:

<!-- DO NOT EDIT: generated by xmldocmd for Moq.AutoMock.dll -->

Do not manually edit these files. Instead, update the XML doc comments in the source .cs files and regenerate.

Markdown Conventions

Frontmatter

Documentation files in this project do not use frontmatter. Start directly with an H1 heading.

Headings

• Use H1 (#) for the page title only (one per file)
• Use H2 (##) for major sections
• Use H3 (###) for subsections
• Do not skip heading levels

Code Blocks

Always include a language identifier:

```csharp
var mocker = new AutoMocker();
var service = mocker.CreateInstance<MyService>();
```

For XML/MSBuild configuration:

```xml
<PropertyGroup>
  <EnableMoqAutoMockerOptionsGenerator>false</EnableMoqAutoMockerOptionsGenerator>
</PropertyGroup>
```

For JSON configuration:

```json
{
  "ConnectionStrings": {
    "mydb": "Host=localhost;Database=mydb"
  }
}
```

Tables

Use standard Markdown tables with alignment:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Value    | Value    | Value    |

Links

Use relative links for internal documentation:

[AutoMocker API Reference](Moq.AutoMock/AutoMocker.md)
[Source Generators](SourceGenerators.md)
[Learn more →](SourceGenerators/UnitTestGenerator.md)

Source Generator Documentation

File Location

Place source generator docs in docs/SourceGenerators/:

Required Sections

All source generator documentation must include these sections in order:

1. Title and Introduction — H1 title, when it activates, what it generates, primary value
2. Features — Bullet list of key capabilities
3. Usage — Basic usage with simple example, then advanced scenarios
4. Generated Extension Methods — Document the actual API generated with method signatures
5. How It Works — Internal mechanism explanation and integration with AutoMocker
6. Advanced Usage — Complex scenarios, type variations, working with dependencies
7. Disabling the Generator — MSBuild property configuration with .csproj example
8. Troubleshooting — Common issues with solutions
9. Best Practices — Practical, actionable guidance with code examples

Introduction Template

# [Name] Extension Generator

When your test project references `[Package.Name]`, this generator creates
`[MethodName]()` extension method(s) for `AutoMocker` that [primary benefit].

Features Template

## Features

- Automatically generates when `[Package.Name]` is referenced
- [Key capability 1]
- [Key capability 2]
- [Integration benefit]

Disabling Generator Template

All extension generators follow this MSBuild property pattern:

<PropertyGroup>
  <EnableMoqAutoMocker[GeneratorName]Generator>false</EnableMoqAutoMocker[GeneratorName]Generator>
</PropertyGroup>

Known properties:

• EnableMoqAutoMockerOptionsGenerator
• EnableMoqAutoMockerFakeLoggingGenerator
• EnableMoqAutoMockerApplicationInsightsGenerator
• EnableMoqAutoMockerKeyedServicesGenerator

Troubleshooting Template

## Troubleshooting

### Extension Method Not Available

1. Verify `[Required.Package]` is referenced in your test project
2. Check that the generator is not disabled in your `.csproj`
3. Rebuild the project to trigger generator execution

Updating the Overview

After creating or updating generator documentation, update docs/SourceGenerators.md:

1. Update generator count in introduction if needed
2. Add/update numbered section with:
   • Link to detailed docs
   • One-sentence description
   • Key Features (3-4 bullets)
   • Quick Example (5-10 lines)
   • "Learn more →" link

Code Example Standards

Use MSTest by Default

[TestClass]
public class MyServiceTests
{
    [TestMethod]
    public void Test_DescriptiveScenario()
    {
        // Arrange
        AutoMocker mocker = new();
        
        // Act
        var service = mocker.CreateInstance<MyService>();

        // Assert
        Assert.AreEqual(expected, actual);
    }
}

Code Style Requirements

• Use modern C# syntax (target-typed new, var)
• Keep examples under 30 lines
• Use realistic domain names (EmailSender, NotificationService, etc.)
• Include using statements when relevant
• Add comments only for non-obvious behavior
• Use // Arrange, // Act, // Assert comments in test examples
• Show both basic and advanced usage patterns

Framework-Specific Examples

When showing framework-specific content, use tables or separate code blocks:

Writing Style Guidelines