Resolve #269 - Complete DI docco

Author: craigfowler

CSF.Screenplay.Abstractions/IPersona.cs

@@ -2,21 +2,22 @@
 
 namespace CSF.Screenplay
 {
-    /// <summary>A persona is a factory for a commonly-used actor</summary>
+    /// <summary>A persona is a factory for a commonly-used <see cref="Actor"/></summary>
     /// <remarks>
     /// <para>
     /// In Screenplay is is recommended to use &amp; reuse memorable actors, which are widely understood and recognisable
-    /// to the development team. This is easier if the composition of an actor is the same across every <see cref="IPerformance"/> in which
-    /// they participate.
+    /// to the development team. This is easier if the composition of an actor is the same across every
+    /// <see cref="IPerformance"/> in which they participate. Personas facilitate this; the persona class serves
+    /// as a consistent factory which creates the same named actor in the same manner every time.
     /// </para>
     /// <para>
-    /// Use classes which derive from this interface to define those memorable
-    /// actors. The persona class should configure the actor it creates with a name and
-    /// a set of abilities appropriate to the actor.
+    /// Developers should create an implementation of this interface for each actor which they wish to
+    /// define, ideally named the same as the name as the Actor.  Each persona implementation should
+    /// name the actor and grant them <xref href="AbilityGlossaryItem?text=the+abilities"/> which are appropriate.
     /// </para>
     /// <para>
-    /// Classes which derive from this interface should constructor-inject any dependencies
-    /// they require, such as those required to grant abilities.
+    /// Instance of persona classes are resolved from the Dependency Injection container, so it is appropriate
+    /// and correct to constructor-inject any services which are required in order to get the ability instances.
     /// </para>
     /// </remarks>
     public interface IPersona : IHasName

CSF.Screenplay.Docs/docs/GettingReports.md

@@ -17,7 +17,7 @@ The default filename includes a representation of the current timestamp, so each
 This path may be altered by specifying a different set of options to the [`AddScreenplay`] service collection extension method.
 
 [`ScreenplayOptions.ReportPath`]: xref:CSF.Screenplay.ScreenplayOptions.ReportPath
-[`AddScreenplay`]: xref:CSF.Screenplay.ScreenplayServiceCollectionExtensions.AddScreenplay(Microsoft.Extensions.DependencyInjection.IServiceCollection,System.Action{CSF.Screenplay.ScreenplayOptions})
+[`AddScreenplay`]: xref:CSF.Screenplay.ScreenplayServiceCollectionExtensions.AddScreenplay(Microsoft.Extensions.DependencyInjection.IServiceCollection)
 
 ## Converting JSON to a human-readable report
 

CSF.Screenplay.Docs/docs/bestPractice/WritingTests.md

@@ -1,6 +1,6 @@
 # Advice for writing tests with Screenplay
 
-Whichever testing integration you choose to use, there are some general pieces of advice and best practice which apply. 
+Whichever testing integration you choose to use, there are some general pieces of advice and best practice which apply.
 
 ## Use high-level tasks
 
@@ -38,16 +38,16 @@ Assertion libraries to consider include [Shouldly] and [Fluent Assertions].
 ## Do not include assertions in performables
 
 It might be tempting to include assertion syntax within [performables] such as [tasks].
-This is not recommended. 
+This is not recommended.
 Where assertions appear within performables:
 
 * They reduce the reusability of the performables
 * They create a dependency between your performables and your testing framework/assertion library
 * They can make test logic harder to read and understand
 
-It is recommended to keep your performables/tasks free from assertions. 
-In your test code, use [questions] or question-like tasks to get values/data from the system under test. 
+It is recommended to keep your performables/tasks free from assertions.
+In your test code, use [questions] or question-like tasks to get values/data from the system under test.
 Write your assertions in your main test logic, asserting that the values retrieved are as-expected.
 
 [tasks]: ../../glossary/Task.md
-[questions]: ../../glossary/Question.md
+[questions]: ../../glossary/Question.md

CSF.Screenplay.Docs/docs/concepts/HowScreenplayAndPerformanceRelate.md

@@ -25,7 +25,7 @@ If Screenplay is not being used for testing, then the consuming logic has the fo
 
 [Performance]: xref:CSF.Screenplay.IPerformance
 [`Screenplay`]: xref:CSF.Screenplay.Screenplay
-[`Create`]: xref:CSF.Screenplay.Screenplay.Create(System.Action{Microsoft.Extensions.DependencyInjection.IServiceCollection},System.Action{CSF.Screenplay.ScreenplayOptions})
+[`Create`]: xref:CSF.Screenplay.Screenplay.Create(System.Action{Microsoft.Extensions.DependencyInjection.IServiceCollection})
 [`BeginScreenplay`]: xref:CSF.Screenplay.Screenplay.BeginScreenplay
 [`ExecuteAsPerformanceAsync<TPerformance>`]: xref:CSF.Screenplay.ScreenplayExtensions.ExecuteAsPerformanceAsync``1(CSF.Screenplay.Screenplay,System.Collections.Generic.IList{CSF.Screenplay.Performances.IdentifierAndName},System.Threading.CancellationToken)
 [`ExecuteAsPerformance`]: xref:CSF.Screenplay.ScreenplayExtensions.ExecuteAsPerformance(CSF.Screenplay.Screenplay,System.Func{System.IServiceProvider,System.Nullable{System.Boolean}},System.Collections.Generic.IList{CSF.Screenplay.Performances.IdentifierAndName},System.Threading.CancellationToken)

CSF.Screenplay.Docs/docs/dependencyInjection/AddingServices.md

@@ -3,7 +3,7 @@
 There are two techniques to add dependency services to Screenplay.
 You may either integrate Screenplay into an existing container for your application or tests or you may add additional services via the static [`Create`] factory method.
 
-[`Create`]: xref:CSF.Screenplay.Screenplay.Create(System.Action{Microsoft.Extensions.DependencyInjection.IServiceCollection},System.Action{CSF.Screenplay.ScreenplayOptions})
+[`Create`]: xref:CSF.Screenplay.Screenplay.Create(System.Action{Microsoft.Extensions.DependencyInjection.IServiceCollection})
 
 ## Integrating with an existing container
 
@@ -29,7 +29,7 @@ var screenplay = Screenplay.Create(services => {
 });
 ```
 
-[`Screenplay.Create`]: xref:CSF.Screenplay.Screenplay.Create(System.Action{Microsoft.Extensions.DependencyInjection.IServiceCollection},System.Action{CSF.Screenplay.ScreenplayOptions})
+[`Screenplay.Create`]: xref:CSF.Screenplay.Screenplay.Create(System.Action{Microsoft.Extensions.DependencyInjection.IServiceCollection})
 
 ## A reminder on lifetime scopes
 

CSF.Screenplay.Docs/docs/dependencyInjection/ConstructorInjectIntoThePersona.md

@@ -1,4 +1,5 @@
 # Injecting services into Personas
+
 Types which derive from [`IPersona`] support constructor-injected dependencies.
 Personas are typically used by either [the cast] or [the stage] to get an [Actor].
 The technique in which they are used means that they are resolved, along with their constructor-injected dependencies, from DI.

CSF.Screenplay.Docs/docs/dependencyInjection/ConstructorInjectionForBindings.md

@@ -1,7 +1,29 @@
 # Constructor injection for bindings
-For frameworks which are based on **binding classes** such as [Reqnroll], services are constructor-injected into binding classes.
 
+For frameworks which are based on **binding classes** such as [Reqnroll], services are constructor-injected into binding classes.
 Use dependencies injected in this way to get access to [commonly-used Screenplay services] and anything else required at the root level of your test logic.
 
 [Reqnroll]: https://reqnroll.net/
 [commonly-used Screenplay services]: InjectableServices.md
+
+## Example
+
+This is an example of a Reqnroll-style binding class with a constructor-injected dependency.
+This would require [installing the Reqnroll test integration] to run.
+Take note of the `stage` parameter in the primary constructor.
+
+```csharp
+[Binding]
+public class SampleSteps(IStage stage)
+{
+    [Given("Simon shows a sample step")]
+    public async Task GivenSimonShowsASampleStep()
+    {
+        var simon = stage.Spotlight<Simon>();
+
+        // ... use the actor with some performables, then make assertions etc
+    }
+}
+```
+
+[installing the Reqnroll test integration]: ../gettingStarted/reqnroll/index.md

CSF.Screenplay.Docs/docs/dependencyInjection/DependencyInjectionScope.md

@@ -5,14 +5,18 @@ uid: DependencyInjectionScopeArticle
 # Dependency injection scope
 
 Developers familiar with dependency injection are likely to be familiar with the concept of [DI Scopes].
-That is - some services which are designated as _scoped_ or _instance per scope_ use a common/shared instance for the lifetime/duration of the scope.
+Screenplay uses this concept; a number of its services are added to the container with _a per-scope lifetime_.
+Screenplay creates **a new DI scope per [Performance]**.
+As you can see on [the diagram of how Actors, Abilities and Performables relate to one another], each [`Screenplay`] contains and executes many performances.
+This scope-creation is handled automatically by the Screenplay framework logic.
 
-Within Screenplay logic, a DI scope is automatically created, with a lifetime matching that of the current [Performance].
 Within a performance, when any of the scoped services (listed below) are injected, each point of injection will receive the same shared instance of that service.
 Instances are independent per-performance; each performance gets its own shared instance of each of the listed services.
 
 [DI Scopes]: https://learn.microsoft.com/en-us/dotnet/core/extensions/dependency-injection#service-lifetimes
 [Performance]: xref:CSF.Screenplay.Performance
+[the diagram of how Actors, Abilities and Performables relate to one another]: ../concepts/MakeupOfAScreenplay.md
+[`Screenplay`]: xref:CSF.Screenplay.Screenplay
 
 ## List of scoped services
 
@@ -25,6 +29,7 @@ The following services are added to DI "per lifetime scope".
 ## List of singleton services
 
 The following services are added to DI as singletons.
+There is only ever a single instance of these services per Screenplay.
 
 * [The Screenplay](xref:CSF.Screenplay.Screenplay)
 * [The event bus](xref:CSF.Screenplay.Performances.PerformanceEventBus)

CSF.Screenplay.Docs/docs/dependencyInjection/InjectionForStandaloneScreenplay.md

@@ -1,17 +1,59 @@
 # Dependency injection for standalone Screenplay
 
-If you are [using Screenplay standalone] then the [`Screenplay.ExecuteAsPerformanceAsync`] permits resolution of dependencies via its parameter.
-That parameter is a `Func<IServiceProvider,CancellationToken,Task<bool?>>`.
-The service provider may be used to resolve dependency services for the performance's logic.
-
-Developers are urged to consider encapsulating their performance logic in implementations of [`IHostsPerformance`].
-Through an overload (extension method) named [`ExecuteAsPerformanceAsync<T>`], developers may specify the concrete implementation of that interface.
-This extension method will resolve that implementation type along with any of its constructor-injected dependencies.
-This avoids the service locator anti-pattern and provides a convenient pattern by which to write performance logic.
-
-Use services resolved from the service provider, or injected into your [`IHostsPerformance`] implementation, to get access to [commonly-used Screenplay services] and anything else required at the root level of your performance logic.
+If you are [using Screenplay standalone] then you are likely using the method [`Screenplay.ExecuteAsPerformanceAsync`] or one of its overloads.
 
 [using Screenplay standalone]: ../gettingStarted/nonTesting/index.md
 [`Screenplay.ExecuteAsPerformanceAsync`]: xref:CSF.Screenplay.Screenplay.ExecuteAsPerformanceAsync(System.Func{System.IServiceProvider,System.Threading.CancellationToken,System.Threading.Tasks.Task{System.Nullable{System.Boolean}}},System.Collections.Generic.IList{CSF.Screenplay.Performances.IdentifierAndName},System.Threading.CancellationToken)
+
+## Recommended: Use `IHostsPerformance`
+
+Developers are urged to consider encapsulating their performance logic in a class which derives from [`IHostsPerformance`].
+Through an overload (extension method) named [`ExecuteAsPerformanceAsync<T>`], developers may specify the concrete implementation type of that class as a generic type parameter.
+This overload of `ExecuteAsPerformanceAsync` will resolve your class which derives from `IHostsPerformance` from dependency injection (_remember to add it to the container!_).
+This resolution will include all the class' dependencies which are constructor-injected and leads to very clean code.
+The service provider is never exposed, thus removing the temptation to use the service locator anti-pattern.
+
 [`IHostsPerformance`]: xref:CSF.Screenplay.IHostsPerformance
 [`ExecuteAsPerformanceAsync<T>`]: xref:CSF.Screenplay.ScreenplayExtensions.ExecuteAsPerformanceAsync``1(CSF.Screenplay.Screenplay,System.Collections.Generic.IList{CSF.Screenplay.Performances.IdentifierAndName},System.Threading.CancellationToken)
+
+### Example of the performance host technique
+
+This example is functionally identical to the example below.
+
+```csharp
+public class MyPerformance(ICast cast) : IHostsPerformance
+{
+    public Task<bool?> ExecutePerformanceAsync(CancellationToken cancellationToken)
+    {
+        var aaron = cast.GetActor<Aaron>();
+        // Further performance logic ...
+    }
+}
+
+// To consume the above:
+await screenplay.ExecuteAsPerformanceAsync<MyPerformance>();
+```
+
+## Alternative: Use a function
+
+The original [`Screenplay.ExecuteAsPerformanceAsync`] overload accepts up to three parameters, the first of which is a function.
+That function should contain the logic which makes up the performance.
+The function (which drives the performance logic) provides two parameters itself:
+
+* An [`IServiceProvider`](xref:System.IServiceProvider)
+* A [`CancellationToken`](xref:System.Threading.CancellationToken)
+
+The serivce provider may be used to resolve services which may be used by the performance logic.
+
+### Example of the function-based technique
+
+This example is functionally identical to the example above.
+
+```csharp
+await screenplay.ExecuteAsPerformanceAsync((services, cancellationToken) => {
+    var cast = services.GetRequiredService<ICast>();
+    var aaron = cast.GetActor<Aaron>();
+    // Further performance logic ...
+});
+
+```

CSF.Screenplay.Docs/docs/dependencyInjection/ParameterInjectionForTests.md

@@ -1,10 +1,28 @@
 # Parameter injection for tests
-For testing frameworks which are based on **test methods** such as [NUnit], services are injected via _method parameter injection_. This is performed directly into each test method which is decorated with the `[Screenplay]` attribute. 
-
-[If Screenplay were to be extended] to work with frameworks such as xUnit or MSTest, then this same technique would be used.
 
+For testing frameworks which are based on **test methods** such as [NUnit], services are injected via _method parameter injection_. This is performed directly into each test method which is decorated with the `[Screenplay]` attribute.
 Use dependencies injected in this way to get access to [commonly-used Screenplay services] and anything else required at the root level of your test logic.
 
+[If Screenplay were to be extended] to work with frameworks such as xUnit or MSTest, then this same technique would be used.
+
 [NUnit]: https://nunit.org/
 [If Screenplay were to be extended]: ../extendingScreenplay/TestIntegrations.md
-[commonly-used Screenplay services]: InjectableServices.md
+[commonly-used Screenplay services]: InjectableServices.md
+
+## Example
+
+This is an example of an NUnit-style test method with a parameter-injected dependency.
+This would require [installing the NUnit test integration] to run.
+Take note of the Screenplay attribute and the `cast` parameter.
+
+```csharp
+[Test, Screenplay]
+public async Task TheSampleTestShouldBeInformative(ICast cast)
+{
+    var janeSmith = cast.GetActor<JaneSmith>();
+
+    // ... use the actor with some performables, then make assertions etc
+}
+```
+
+[installing the NUnit test integration]: ../gettingStarted/nunit3/index.md