Should we document Modifiers, e.g. Using

[OsirisTerje]

The modifiers that can be used are somewhat poorly documented. Some are documented where they are used, like Within, but e.g. Using is only briefly mentioned with no documentation nor examples of use.

All documentation should have examples of usage, placed in the Snippets folder.

The Using is used on multiple constraints, and since their use is nearly similar, should they be documented in one place, and variations documented there, or should we document them for every constraint. If the former, the constraints should be expanded with links to the usage documentation.

I've also noticed that not all constraints where it can be applied mention the Usage modifier.

I also believe we lack a complete dictionary over the different modifiers we use.

@nunit/framework-team ?

[manfred-brands]

Indeed, Using exists on more constraints than shown in the documentation, e.g. CollectionSubsetConstraint, UniqueItemsConstraint and more.

It would be good to have a section on comparison and that all (I hope) comparison constraints have the Using modifier to allow specifying a comparison option. Note that not all Using constraints are the same. The ones that compare order have less overloads than the one comparing for equality.

I only stumbled over the AsCollection constraint, which I find very confusing, when creating a Analyzer CodeFix to convert CollectionAssert to the equivalent Assert.That.

The problem I have with documenting the constraints is that hardly any developer uses the constraints directly by calling their constructors. I thought that @SeanKilleen created a ticket (or asked a question) about documenting the static classes, but cannot find it. But not sure how to organize it any different either.

[OsirisTerje]

The problem I have with documenting the constraints is that hardly any developer uses the constraints directly by calling their constructors

I fully agree. I believe we should focus on user-centric documentation. Now it is a mix of user and reference. I hope we can sort that out later, so in this case, we could add either a modifiers section, and also document comparisons directly, like a tutorial section. @SeanKilleen - what's your thoughts here?

[SeanKilleen]

@OsirisTerje @manfred-brands I think the overall challenge, in my work on the project so far, is that we have three docs goals:

• We want all the parts of the framework to be documented so their usage is clear.
• We want user-centric documentation and more guidance-related docs and pathfinding
• We want to socialize the neat tidbits about NUnit that could make our users' lives easier but may not be things that occur to them (and that might be the source of a lot of GH issue resolutions).

I think these are separate goals, and they're all valuable, but I think they're different kinds of content.

Maybe it's about forcing ourselves to put types of content into those buckets so as to consider the audience and format and where the content should ultimately live.

Perhaps something like:

• Code-related items (e.g. you can use Using() on the CollectionSubsetConstraint - this seems like it would benefit from working toward getting the Docfx hooked up to the source code, so that it can be melded with the docs site. This would allow this to be made clear in the xmldoc comments in the codebase itself.
• Neat Tips: Maybe we dump these into a "Tips & Tricks" or "NUnit Recipes" area where we talk through avoiding common pitfalls, or things we see folks do that might benefit from some of the syntactical sugar we offer.
• Longer-form, opinionated Guidance: I think an opinionated guide such as a mini-book is the way to go here. I've gotten WIP: NUnit on-ramp minibook #745 going and I think this might be the push I need to dust that off and start working through it, and focusing on merging @OsirisTerje 's feedback into the PR and getting it merged just to have something started.

My new job had made me hesitant to dig into any huge stuff with NUnit the last 3 months, but I think I have my feet under me there now and I really would like to set these efforts up for success. I'll see what I can do to put together a graph of blockers and start knocking away at them.