nunit-attribute-documentation

name	NUnit Attribute Documentation
description	Create and update documentation for NUnit attributes following the established template structure

NUnit Attribute Documentation

This skill describes how to create and update documentation for NUnit attributes.

Documentation Template Structure

Each attribute documentation file in docs/articles/nunit/writing-tests/attributes/ should follow this structure:

# AttributeName

Brief description of what the attribute does.

## Constructor

```csharp
AttributeName(paramType paramName)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `paramName` | `Type` | Description of the parameter. Include important notes like valid ranges or default behavior. |

## Properties

| Property | Type | Description | Default |
|----------|------|-------------|---------|
| `PropertyName` | `Type` | Description of the property. | `defaultValue` |

> [!NOTE]
> Version notes if applicable (e.g., "Added in **NUnit 4.5.0**").

## Applies To

Use a table with checkmarks to show where the attribute can be applied:

| Target | Supported |
|--------|-----------|
| Test Methods | ✅ |
| Test Fixtures (Classes) | ✅ |
| Assemblies | ❌ |

Use ✅ (green checkmark) where the attribute applies, ❌ (red X) where it doesn't.

## Example

[!code-csharp[ExampleName](~/snippets/Snippets.NUnit/Attributes/AttributeNameExamples.cs#RegionName)]

## Notes

1. Important behavioral notes
2. Limitations
3. Edge cases

## See Also

* [Related Attribute](relatedattribute.md)

For Parameterless Attributes

Use a simpler "Usage" section instead of Constructor/Properties:

## Usage

This is a parameterless attribute that can only be applied to [target].

```csharp
[AttributeName]
```

Workflow for Updating Attribute Documentation

Repository Layout Assumption: This workflow assumes you have cloned both repositories as siblings:

• <workspace>/nunit/ - The NUnit framework source code (nunit/nunit)
• <workspace>/docs/ - This documentation repository (nunit/docs)

Adjust paths below to match your local setup.

Step 1: Find the Source Code

Search for the attribute class in the NUnit framework:

# Find the attribute source file (adjust path to your nunit repo location)
grep -r "class AttributeNameAttribute" ../nunit --include="*.cs"

The source is typically at: <nunit-repo>/src/NUnitFramework/framework/Attributes/AttributeNameAttribute.cs

Step 2: Analyze the Source Code

From the source file, extract:

• Constructor parameters and their XML doc comments
• Properties with their types, descriptions, and default values
• AttributeUsage to determine valid targets (Class, Method, Assembly)
• Whether Inherited = true

Step 3: Check for Existing Unit Tests

# Find unit tests for the attribute (adjust path to your nunit repo location)
grep -r "AttributeName" ../nunit/src/NUnitFramework/tests --include="*.cs"

Tests are typically at: <nunit-repo>/src/NUnitFramework/tests/Attributes/AttributeNameAttributeTests.cs

Unit tests provide good examples of usage patterns and edge cases.

Step 4: Create Snippet File

Create a new file at: docs/snippets/Snippets.NUnit/Attributes/AttributeNameAttributeExamples.cs

Follow this pattern:

using NUnit.Framework;

namespace Snippets.NUnit.Attributes
{
    public class AttributeNameAttributeExamples
    {
        #region ExampleName
        [TestFixture]
        public class ExampleTests
        {
            [Test]
            public void ExampleTest()
            {
                // Test code that demonstrates the attribute
                Assert.That(true, Is.True);
            }
        }
        #endregion

        #region AnotherExample
        // More examples...
        #endregion
    }
}

Key points:

• Use #region / #endregion to mark code sections
• Region names are used in the markdown reference: #RegionName
• Tests must actually pass - avoid stub code that doesn't work
• If you need helper classes, make them private nested classes

Step 5: Update the Markdown Documentation

Reference snippets using DocFX syntax:

[!code-csharp[ExampleName](~/snippets/Snippets.NUnit/Attributes/AttributeNameExamples.cs#ExampleName)]

Step 6: Build and Test

Always verify the snippets compile and tests pass. From the docs repository root:

# Build
dotnet build docs/snippets/Snippets.slnx

# Run all tests
dotnet test docs/snippets/Snippets.slnx --no-build

# Run specific tests
dotnet test docs/snippets/Snippets.slnx --no-build --filter "FullyQualifiedName~AttributeNameExamples" --verbosity normal

Step 7: Update the Plan File

Mark the attribute as done in docs-improvement-plan.md:

| AttributeName | Done | Brief notes about what was added |

Common Attribute Patterns

Attributes with Constructor Parameters Only

Examples: Retry, Repeat, MaxTime, Order

Attributes with Properties

Examples: Retry (has RetryExceptions), TestCase (has many named parameters)

Parameterless Attributes

Examples: SingleThreaded, NonParallelizable, Combinatorial

Enum-based Attributes

Examples: Parallelizable (takes ParallelScope), Apartment (takes ApartmentState)

Document the enum values in a table.

Command Line Documentation Guidelines

When documenting command line usage:

1. Use appropriate code fences - Use ```shell for command line examples, not ```bash, ```text, or untagged code blocks.

2. Prioritize dotnet test - Always mention dotnet test before the NUnit console runner, as it is used far more frequently.

3. Include runsettings equivalents - When mentioning console runner options (like --timeout, --workers, etc.), note that these settings can also be configured for dotnet test via the NUnit adapter's .runsettings file.

Example:

## Command Line Usage

```shell
# dotnet test (via NUnit adapter)
dotnet test --filter "TestCategory=Fast"

# Or via runsettings
dotnet test --settings test.runsettings

# NUnit Console Runner
nunit3-console MyTests.dll --where "cat == Fast"
```

Quality Checklist

Before marking an attribute as done:

• Constructor section with parameter table (if applicable)
• Properties section with defaults (if applicable)
• At least one working code example in snippets folder
• Examples build without errors
• Example tests pass
• Notes section with important behavioral info
• See Also section with related attributes
• Plan file updated