Resolve #225 - Add sample task docs

Author: craigfowler

CSF.Screenplay.Docs/docs/writingPerformables/AvoidBranchingLogic.md

@@ -3,17 +3,22 @@
 [Performances] are written _a lot like scripts_.
 Where possible, [Performables] should avoid branching or looping logic.
 _This is particularly true_ when Screenplay is being used [as a tool for testing].
-Good test logic has [a cyclomatic complexity] of precisely one.
+Good test logic has [a cyclomatic complexity] as close to one as possible.
 
 Sometimes looping logic is unavoidable and desirable in a Screenplay, imagine a performable which has an [Actor] repeat a process `N` times.
-This is acceptable if used judiciously.
+Sometimes branching logic is required to deal with external systems which present differing behaviour.
+The [Selenium Extension] makes use of this technique to accomodate different web browsers and web driver implementations.
+Such logic is acceptable if used judiciously.
 
-Performables should always avoid branching logic like `if` or `switch` though, and _should never_ contain such logic when being used for tests.
-If more than one mode of operation is required then write more than one performable.
-The path through a Performance should be completely deterministic, short of an unexpected error or failure.
+Perhaps the best guideline is for the developer to ask themselves:
+
+> Could I separate this into two or more tasks and decide which I need at the point of usage?
+
+If the answer is "yes", then it's often better to do just that, rather than write a multi-function Task.
 
 [Performances]: xref:CSF.Screenplay.IPerformance
 [Performables]: ../../glossary/Performable.md
 [as a tool for testing]: ../bestPractice/SuitabilityAsATestingTool.md
 [a cyclomatic complexity]: https://en.wikipedia.org/wiki/Cyclomatic_complexity
 [Actor]: xref:CSF.Screenplay.Actor
+[Selenium Extension]: ../extensions/selenium/index.md

CSF.Screenplay.Docs/docs/writingPerformables/index.md

@@ -12,9 +12,40 @@ On the other hand, it is very likely that developers will need to write [Tasks],
 
 ## A sample Task
 
-Here is an annotated example of a [Task] which makes use of a fictitious Action and a fictitious Question.
+Here is an annotated example of a [Task] which makes use of a fictitious Action and Question.
 
-TODO: Write this docco
+```csharp
+// A parameter is constructor injected, so that this task may be parameterised.
+// This is entirely optional, if no parameters are needed then none need be added.
+public class BuyMilkIfNeeded(int cupsOfCoffee) : IPerformable, ICanReport
+{
+    // Always implement the ICanReport interface if possible.
+    // Write a human-readable report of what the Task does.
+    // There's no need to detail the work done by consumed performables; they will get their own reports.
+    public ReportFragment GetReportFragment(Actor actor, IFormatsReportFragment formatter)
+        => formatter.Format("{Actor} adds milk to their shopping list, if they need it to make {Cups} cup(s) of coffee", actor, cupsOfCoffee);
+
+    public async ValueTask PerformAsAsync(ICanPerform actor, CancellationToken cancellationToken = default)
+    {
+        // Use of a fictitious Question, remember to await it and to pass the cancellation token.
+        // This question, which looks in the refridgerator and gets a decimal which represents the
+        // quantity of an item inside, measured in litres, is ficitious.
+        // It is consumed here from a fictitious builder method.
+        var litresOfMilk = await actor.PerformAsync(LookInTheRefridgeratorFor("Milk").AndTellMeHowMuchRemainsInLitres(), cancellationToken);
+        var isEnough = IsThisEnoughMilkToMakeCoffee(cupsOfCoffee, litresOfMilk);
+        if(!isEnough)
+            // Use of a fictitious Action, again remember to await it and pass the cancellation token.
+            await actor.PerformAsync(AddToMyShoppingList("Milk"), cancellationToken);
+        
+    }
+
+    static bool IsThisEnoughMilkToMakeCoffee(int cupsOfCoffee, decimal litresOfMilk)
+    {
+        // Implementation omitted, determines if the litresOfMilk param is enough milk to make
+        // the indicated number of cupsOfCoffee.
+    }
+}
+```
 
 [Task]: ../../glossary/Task.md