Improved all attribute docs

[OsirisTerje]

I have changed the docs to a more common format, with clear documentation of ctors and properties. And also moved all examples to the snippets folder, and where none where present, created examples.

I have also added a claude skill for attribute documentation, and a plan for this and further work.

Based on the skill, a series of new examples have been added when there are more actual usage patterns that was described earlier, and in some cases the structure have also been improved, and since AI is good with language, the documents now looks better - to me at least......

I have used both Claude and Cursor to work with the documentation, small parts at a time. I have asked them to look at the source code and ensure we have all properties and usage the code allow in the documentation. In some cases I have also had it look at the unit tests we have to gather information on usage.

I also had to change all document path links (we should not use those) into xref links and then adding uid's in every file that was referenced.

[Copilot]

Pull request overview

This PR standardizes and expands documentation for a set of under-documented NUnit attributes by introducing a consistent template (constructors/properties/notes/see-also), and by moving/adding working code examples into the snippets project. It also adds internal .claude guidance (skill + plan) to systematize further documentation improvements.

Changes:

• Reworked multiple attribute docs pages into a consistent, more structured format (constructor/properties/applies-to/notes/see-also).
• Added new NUnit snippet example files for the updated attributes and wired docs pages to snippet regions.
• Added a .claude skill and a docs improvement plan to guide future attribute documentation work.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
docs/snippets/Snippets.NUnit/Attributes/SingleThreadedAttributeExamples.cs	Adds snippet coverage for SingleThreadedAttribute.
docs/snippets/Snippets.NUnit/Attributes/SetUICultureAttributeExamples.cs	Adds snippet coverage for SetUICultureAttribute (fixture/method/combined usage).
docs/snippets/Snippets.NUnit/Attributes/SetCultureAttributeExamples.cs	Adds snippet coverage for SetCultureAttribute (fixture/method/combined usage).
docs/snippets/Snippets.NUnit/Attributes/RepeatAttributeExample.cs	Updates the repeat snippet’s explicit reason text.
docs/snippets/Snippets.NUnit/Attributes/PropertyAttributeExamples.cs	Adds snippet coverage for PropertyAttribute, including custom derived attribute usage.
docs/snippets/Snippets.NUnit/Attributes/OrderAttributeExamples.cs	Adds snippet coverage for OrderAttribute (methods/fixtures/gaps pattern).
docs/snippets/Snippets.NUnit/Attributes/MaxTimeAttributeExamples.cs	Adds snippet coverage for MaxTimeAttribute (basic + precedence example).
docs/snippets/Snippets.NUnit/Attributes/DatapointAttributeExamples.cs	Adds snippet coverage for Datapoint/DatapointSource patterns used by theories.
docs/snippets/Snippets.NUnit/Attributes/CultureAttributeExamples.cs	Adds snippet coverage for CultureAttribute (include/exclude/reason/fixture usage).
docs/articles/nunit/writing-tests/attributes/singlethreaded.md	Rewrites doc page into structured template and links new snippet.
docs/articles/nunit/writing-tests/attributes/setuiculture.md	Rewrites doc page into structured template and links new snippets.
docs/articles/nunit/writing-tests/attributes/setculture.md	Rewrites doc page into structured template and links new snippets.
docs/articles/nunit/writing-tests/attributes/retry.md	Rewrites doc page into structured template and clarifies RetryExceptions.
docs/articles/nunit/writing-tests/attributes/repeat.md	Rewrites doc page into structured template and updates notes/links.
docs/articles/nunit/writing-tests/attributes/property.md	Rewrites doc page into structured template and links new snippets.
docs/articles/nunit/writing-tests/attributes/order.md	Rewrites doc page into structured template and links new snippets.
docs/articles/nunit/writing-tests/attributes/maxtime.md	Rewrites doc page into structured template and links new snippets.
docs/articles/nunit/writing-tests/attributes/datapointsource.md	Rewrites doc page into structured template and links new snippet region.
docs/articles/nunit/writing-tests/attributes/datapoint.md	Rewrites doc page into structured template and links new snippet regions.
docs/articles/nunit/writing-tests/attributes/culture.md	Rewrites doc page into structured template and links new snippets.
.claude/skills/attribute-documentation/skill.md	Adds a reusable internal template/workflow for attribute docs updates.
.claude/plans/docs-improvement-plan.md	Adds a tracking plan for attribute documentation improvements.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[OsirisTerje]

@SeanKilleen Can you have a new look?

I know there are a lot of files and changes, but just a quick check please :-) I'll buy you dinner next time we meet !

[Copilot]

Pull request overview

Copilot reviewed 147 out of 147 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[SeanKilleen]

@OsirisTerje I'll take a look soon as I'm able, probably in a few hours. Pretty sure I owe you dinner for doing all the heavy work! :)

[OsirisTerje]

The plan for improvement, now done:

NUnit Attribute Documentation Improvement Plan

Overview

This plan outlines the work needed to improve the documentation for NUnit attributes located in docs/articles/nunit/writing-tests/attributes/. The goal is to bring all attribute documentation up to a consistent standard using the template established in retry.md.

Template Structure

Each attribute documentation file should follow this structure:

1. Title - # AttributeName
2. Introduction - Brief description of what the attribute does
3. Constructor(s) - Code signature with parameter table (Parameter, Type, Description)
4. Properties - Table with Property, Type, Description, and Default columns
5. Example(s) - Code snippets demonstrating usage
6. Notes - Important behavioral information, limitations, edge cases
7. See Also - Links to related attributes

Priority List - Top 10 Attributes Needing Updates

1. SingleThreaded (Score: 9/10 - Critical)

• File: singlethreaded.md
• Current State: Minimal (only 7 lines)
• Missing:
  • No Constructor section
  • No Properties section
  • No usage examples
  • No detailed explanation of behavior with ParallelScope settings
• Source file to check: SingleThreadedAttribute.cs

2. SetCulture (Score: 8.5/10)

• File: setculture.md
• Current State: Minimal/Partial
• Missing:
  • No Constructor section with parameter details
  • No Properties section
  • No culture inheritance behavior documentation
  • Missing culture reset behavior after test completes
  • No supported culture format details
• Source file to check: SetCultureAttribute.cs

3. SetUICulture (Score: 8.5/10)

• File: setuiculture.md
• Current State: Minimal/Partial
• Missing:
  • No Constructor section
  • No Properties section
  • Missing UI culture vs regular culture differences
  • No default culture value documentation
• Source file to check: SetUICultureAttribute.cs

4. Culture (Score: 8/10)

• File: culture.md
• Current State: Minimal
• Missing:
  • No formal Constructor section
  • No Properties/Parameters table
  • Limited culture format guidance (en-GB vs de syntax)
  • No exclude behavior examples
  • Missing interaction notes with SetCulture
• Source file to check: CultureAttribute.cs

5. Property (Score: 7.5/10)

• File: property.md
• Current State: Partial
• Missing:
  • No formal Constructor parameters table
  • No type information for name/value pairs
  • Limited examples
  • Missing multiple property support documentation
• Source file to check: PropertyAttribute.cs

6. Datapoint (Score: 7/10)

• File: datapoint.md
• Current State: Minimal
• Missing:
  • No Constructor section (field-only attribute)
  • Missing explicit list of supported types
  • No behavior matrix for automatic datapoint generation
  • No type-matching rules explanation
• Source file to check: DatapointAttribute.cs

7. DatapointSource (Score: 7/10)

• File: datapointsource.md
• Current State: Minimal
• Missing:
  • No formal Constructor section
  • Missing parameter documentation
  • No IEnumerable vs array pattern examples
  • No method vs property vs field usage guidance
• Source file to check: DatapointSourceAttribute.cs

8. MaxTime (Score: 6.5/10)

• File: maxtime.md
• Current State: Partial (31 lines)
• Missing:
  • No formal Constructor section
  • Missing property documentation
  • No timeout behavior details (immediate vs graceful)
  • No timing precision discussion
• Source file to check: MaxTimeAttribute.cs

9. Order (Score: 6.5/10)

• File: order.md
• Current State: Partial
• Missing:
  • No formal Constructor parameters table
  • Missing property documentation
  • No ordering scope rules across nested fixtures
  • No edge case handling (negative orders, same order values)
• Source file to check: OrderAttribute.cs

10. Repeat (Score: 6.5/10)

• File: repeat.md
• Current State: Partial
• Missing:
  • No formal Constructor section
  • Missing StopOnFailure property table with defaults
  • No RepeatAttribute with parameterized tests interaction docs
  • No failure collection behavior details
• Source file to check: RepeatAttribute.cs

Additional Attributes Needing Work (Ranks 11-15)

11. Random (Score: 6/10)

• Constructor signatures exist but not in table format
• Missing property defaults and Guid constraints

12. NonTestAssembly (Score: 5.5/10)

• Parameterless attribute, minimal but functional
• Needs more context and edge case examples

13. LevelOfParallelism (Score: 5/10)

• No formal Constructor section
• Missing performance tuning guidance

14. Apartment (Score: 5/10)

• No formal Constructor parameters section
• Missing ApartmentState enum documentation

15. TestOf (Score: 5/10)

• Minimal documentation
• Missing constructor and property details

Documentation Quality Summary

Quality Level	Count	Attributes
Good	~14	CancelAfter, NetPlatform, NoTests, OneTimeSetUp, OneTimeTearDown, Parallelizable, TestFixture, TestCaseSource, Test, TestCase, Explicit, Theory, UnhandledExceptionHandling, FixtureLifeCycle
Adequate	~14	Apartment, Combinatorial, DefaultFloatingPointTolerance, Description, Ignore, Range, Sequential, Setup, SetupFixture, TearDown, Values, ValueSource, Timeout, Platform, Pairwise
Minimal	~23	SingleThreaded, SetCulture, SetUICulture, Culture, Property, Datapoint, DatapointSource, MaxTime, Order, Repeat, Random, NonTestAssembly, LevelOfParallelism, TestOf, and others

Key Documentation Gaps Across All Attributes

1. Parameter documentation: Most attributes lack formal parameter tables with types, defaults, and ranges
2. Property documentation: Even when constructors exist, properties/defaults rarely documented
3. Interaction documentation: Limited guidance on how attributes combine
4. Edge cases: Minimal discussion of boundary conditions, invalid values, error handling
5. Performance notes: Almost no documentation on performance implications
6. Real-world examples: Most have 1-2 basic examples only

Reference: Completed Template

See retry.md for the completed template example with:

• Constructor section with parameter table
• Properties section with defaults
• Version notes where applicable
• Structured examples
• Consolidated notes section
• See Also links

Progress Tracking

Attribute	Status	Notes
Retry	Done	Template established
SingleThreaded	Done	Parameterless attribute, added Usage/Example/Notes/See Also
SetCulture	Done	Added Constructor table, Applies To section, 3 examples
SetUICulture	Done	Added Constructor table, Applies To section, 3 examples
Culture	Done	Added Constructors, Properties table, Include/Exclude examples
Property	Done	Added Constructors, custom attribute examples, TestContext access
Datapoint	Done	Added Usage section, examples with enums, auto-datapoints table
DatapointSource	Done	Added Usage section, field/property/method examples
MaxTime	Done	Added Constructor, examples, comparison with CancelAfter
Order	Done	Added Constructor, examples with gaps pattern
Repeat	Done	Added Constructors, Properties table with StopOnFailure
Random	Done	Added Constructors with type variants, Properties (Distinct), Supported Types table
NonTestAssembly	Done	Assembly-level config, inline examples acceptable
LevelOfParallelism	Done	Assembly-level config, inline examples acceptable
Apartment	Done	Added Constructor, ApartmentState Values table, snippet examples
TestOf	Done	Added Constructors (Type/string), snippet examples
Author	Done	Added Constructors, Applies To, Alternative Syntax, existing snippet
Description	Done	Added Constructor, snippet examples, named parameter syntax
Category	Done	Added Constructors, Properties, command line usage (dotnet test + console)
RequiresThread	Done	Added Constructors, snippet examples with apartment state
Timeout	Done	Added Constructor, .NET 5+ alternatives table, deprecation warnings
Combinatorial	Done	Added Usage, Applies To table, updated notes and examples
DefaultFloatingPointTolerance	Done	Added Constructor table, Applies To table, clarified scope behavior
Ignore	Done	Added Constructor, Properties (Until), Applies To table, individual case guidance
Range	Done	Added Constructors table, parameter applicability, notes on combining strategy
Sequential	Done	Added Usage, Applies To table, pairing behavior notes
Pairwise	Done	Added Usage, Applies To table, snippet example, notes
Values	Done	Added Constructors, parameter applicability, dedicated snippets
ValueSource	Done	Added Constructors, parameter applicability, source requirements, snippet
Platform	Done	Added Constructors/Properties, Applies To table, snippet example
Explicit	Done	Added Constructors, Applies To table, snippet examples, retained CLI guidance
SetUp	Done	Added Usage, applies-to table, snippet example, clarified lifecycle notes
TearDown	Done	Added Usage, applies-to table, snippet example, clarified teardown guarantees
OneTimeSetUp	Done	Added Usage, applies-to table, snippet example, fixture lifecycle notes
OneTimeTearDown	Done	Added Usage, applies-to table, snippet example, fixture lifecycle notes
SetUpFixture	Done	Added Usage, applies-to table, snippet example, setup fixture constraints
TestFixtureSetUp	Done	Marked legacy status, added applies-to table, pointed to OneTimeSetUp
TestFixtureTearDown	Done	Fixed deprecation text, added applies-to table, pointed to OneTimeTearDown
TestAssemblyDirectoryResolve	Done	Added Applies To table and snippet-based example
TestFixtureSource	Done	Added constructors/properties tables and applies-to section
NetPlatform	Done	Added constructors/properties tables and applies-to section
CancelAfter	Done	Constructor/applies-to, fixed CancellationToken link, TestCase snippet
FixtureLifeCycle	Done	Constructor/properties/applies-to, aligned with SingleInstance/per-test
NoTests	Done	Constructor/applies-to, TestStatus table, scenarios as snippets
Parallelizable	Done	Constructors/properties/applies-to, kept ParallelScope docs
NonParallelizable	Done	UID, Usage, applies-to, queue behavior
Test	Done	UID, Usage, Properties, applies-to, snippet examples
TestCase	Done	Constructors summary, applies-to (method-only)
Theory	Done	Constructor (searchInDeclaringTypes), applies-to
TestFixture	Done	Constructors summary, applies-to (class-only)
TestCaseSource	Done	Constructors/Properties tables, applies-to; removed duplicate Named Parameters
Author / Timeout / Category / Apartment / Description / RequiresThread / TestOf	Done	Bullet Applies To replaced with standard three-column table
Retry	Done	Applies To table (method-only)
UnhandledExceptionHandling	Done	Applies To table (method, fixture, assembly)

[OsirisTerje]

@SeanKilleen Any further comments, or can I merge it ?

[SeanKilleen]

@OsirisTerje give me a little time. You asked for review at 11pm last night my time and I'm in the middle of a workday now. Will review when I can

[OsirisTerje]

Sorry @SeanKilleen . I am not expecting you at all to react immediately. I know we are on different time zones. 😃