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

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

For XML/MSBuild configuration:

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

For JSON configuration:

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

### Tables

Use standard Markdown tables with alignment:

```markdown
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Value    | Value    | Value    |
```

### Links

Use relative links for internal documentation:

```markdown
[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

```markdown
# [Name] Extension Generator

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

### Features Template

```markdown
## 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:

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

Known properties:
- `EnableMoqAutoMockerOptionsGenerator`
- `EnableMoqAutoMockerFakeLoggingGenerator`
- `EnableMoqAutoMockerApplicationInsightsGenerator`
- `EnableMoqAutoMockerKeyedServicesGenerator`

### Troubleshooting Template

```markdown
## 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

```csharp
[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

```markdown
### 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:

```csharp
[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/`