doc-writer

name	doc-writer
description	Guidelines for producing accurate and maintainable documentation for Moq.AutoMocker. Use when writing or updating API docs, source generator docs, tutorials, README content, or any documentation in the docs/ folder.

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

Generator	File
Unit Test	UnitTestGenerator.md
Options	OptionsExtensionGenerator.md
Fake Logging	FakeLoggingExtensionGenerator.md
Application Insights	ApplicationInsightsExtensionGenerator.md
Keyed Services	KeyedServicesExtensionGenerator.md

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:

Framework	Detection	Attributes Used
MSTest	References Microsoft.VisualStudio.TestTools.UnitTesting	[TestMethod]
xUnit	References xunit.core	[Fact]
NUnit	References nunit.framework	[Test]
TUnit	References TUnit.Core	[Test] (async)

Writing Style Guidelines

Voice and Tone

• Use second person ("you") when addressing the reader
• Use active voice ("Create a mock" not "A mock is created")
• Use imperative mood for instructions ("Add the attribute" not "You should add the attribute")
• Be concise but complete
• Be professional but approachable

Terminology

Use consistent terminology throughout:

Preferred	Avoid
AutoMocker	auto mocker, Auto Mocker
mock	fake, stub (unless technically accurate)
source generator	code generator, analyzer
extension method	helper method (for generated methods)
CreateInstance<T>()	create instance, build (when referring to the method)
GetMock<T>()	get mock (when referring to the method)

Formatting Conventions

• Use bold for UI elements and important terms on first use
• Use backticks for code references inline: types, methods, properties, parameters
• Use "→" for "learn more" navigation links
• Use ✅ and ❌ for correct/incorrect examples
• Spell out numbers under 10, use digits for 10+

Project-Specific Context

• Package: All source generators ship in the Moq.AutoMock NuGet package (not separate packages)
• Namespace: Generated code is in the Moq.AutoMock namespace
• Target: Extension methods extend the AutoMocker class
• Frameworks: Supports MSTest, xUnit, NUnit, and TUnit
• Default State: All generators are enabled by default
• Activation: Most generators activate when specific NuGet packages are referenced
• Target Frameworks: netstandard2.0 and netstandard2.1

Updating the README

The project README.md at the repository root contains:

• Badge links (CI, NuGet)
• Quick-start usage examples
• Links to the docs/ folder

When making significant documentation changes, ensure the README links and descriptions remain accurate. Keep README examples minimal — point readers to docs/ for details.

Common Patterns

Diagnostic Error Documentation

### AMG0001: Test class must be partial

**Error:** When using `[ConstructorTests]`, your test class must be declared as `partial`.

```csharp
// ❌ Error
[ConstructorTests(TargetType = typeof(MyClass))]
public class MyClassTests { }

// ✅ Correct
[ConstructorTests(TargetType = typeof(MyClass))]
public partial class MyClassTests { }

### Feature with Before/After Examples

Show the problem, then the solution:

```markdown
**Without** the generator, you'd write this manually:

```csharp
// 20+ lines of boilerplate...

With the generator, just add one attribute:

[ConstructorTests(TargetType = typeof(MyService))]
public partial class MyServiceTests { }

### Cross-Referencing

End pages with a "See also" section linking to:
- Related generator documentation
- AutoMocker API reference
- NuGet package page
- GitHub repository

```markdown
## See Also

- [AutoMocker API Reference](../Moq.AutoMock/AutoMocker.md)
- [Source Generators Overview](../SourceGenerators.md)
- [Moq.AutoMock on NuGet](https://www.nuget.org/packages/Moq.AutoMock)

Testing Documentation

Before submitting documentation:

1. Verify links: Ensure all internal links resolve to existing files
2. Validate code: Confirm all code examples compile and are consistent with current API
3. Check structure: Verify required sections are present and in order
4. Review formatting: Ensure Markdown renders correctly
5. Analyze source: Cross-reference generator docs against the actual source code in Moq.AutoMocker.Generators/ and test examples in GeneratorTests/