From 7ef01c93d1e33df4ef3716b00087d4cebf1dfc27 Mon Sep 17 00:00:00 2001
From: Artyom <worldbeater-dev@yandex.ru>
Date: Fri, 18 Jan 2019 18:33:55 +0300
Subject: [PATCH] housekeeping: Add ReactiveCommand usage examples (#1919)

* housekeeping: Add ReactiveCommand usage examples

* Prefer InvokeCommand() over Execute()

But mention both aproaches.

* Remove trailing whitespace
---
 .../ReactiveCommand/ReactiveCommand.cs        | 46 +++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/src/ReactiveUI/ReactiveCommand/ReactiveCommand.cs b/src/ReactiveUI/ReactiveCommand/ReactiveCommand.cs
index 5347852fe7..1638111f08 100644
--- a/src/ReactiveUI/ReactiveCommand/ReactiveCommand.cs
+++ b/src/ReactiveUI/ReactiveCommand/ReactiveCommand.cs
@@ -25,6 +25,52 @@ namespace ReactiveUI
     /// <para>
     /// This non-generic base class defines the creation behavior of the ReactiveCommand's.
     /// </para>
+    /// <para>
+    /// <see cref="ReactiveCommand{TInput, Output}"/> adds the concept of Input and Output generic types.
+    /// The Input is often passed in by the View and it's type is captured as TInput, and the Output is
+    /// the result of executing the command which type is captured as TOutput.
+    /// </para>
+    /// <para>
+    /// <see cref="ReactiveCommand{TInput, Output}"/> is <c>IObservable</c> which can be used like any other <c>IObservable</c>.
+    /// For example, you can Subscribe() to it like any other observable, and add the output to a List on your view model.
+    /// The Unit type is a functional programming construct analogous to void and can be used in cases where you don't
+    /// care about either the input and/or output value.
+    /// </para>
+    /// <para>
+    /// Creating synchronous reactive commands:
+    /// <code>
+    /// <![CDATA[
+    /// // A synchronous command taking a parameter and returning nothing.
+    /// var command = ReactiveCommand.Create<int, Unit>(x => Console.WriteLine(x));
+    ///
+    /// // This outputs 42 to console.
+    /// command.Execute(42).Subscribe();
+    ///
+    /// // A better approach is to invoke a command in response to an Observable<T>.
+    /// // InvokeCommand operator respects the command's executability. That is, if
+    /// // the command's CanExecute method returns false, InvokeCommand will not
+    /// // execute the command when the source observable ticks.
+    /// Observable.Return(42).InvokeCommand(command);
+    /// ]]>
+    /// </code>
+    /// </para>
+    /// <para>
+    /// Creating asynchronous reactive commands:
+    /// <code>
+    /// <![CDATA[
+    /// // An asynchronous command that waits 2 seconds and returns 42.
+    /// var command = ReactiveCommand.CreateFromObservable<Unit, int>(
+    ///      () => Observable.Return(42).Delay(TimeSpan.FromSeconds(2))
+    /// );
+    ///
+    /// // Calling the asynchronous reactive command:
+    /// // Observable.Return(Unit.Default).InvokeCommand(command);
+    ///
+    /// // Subscribing to values emitted by the command:
+    /// command.Subscribe(Console.WriteLine);
+    /// ]]>
+    /// </code>
+    /// </para>
     /// </remarks>
     [SuppressMessage("StyleCop.CSharp.MaintainabilityRules", "SA1402:FileMayOnlyContainASingleType", Justification = "Same class just generic.")]
     public static class ReactiveCommand