trying to improve doco for Elm/MVU newbies

h0lg · h0lg · commit 7339a571d8da · 2024-09-10T20:12:05.000+02:00
diff --git a/src/Fabulous/Cmd.fs b/src/Fabulous/Cmd.fs
@@ -3,16 +3,35 @@
 open System.Threading
 open System.Threading.Tasks
 
-/// Dispatch - feed new message into the processing loop
+/// <summary>
+/// A function that feeds a new Message into the processing loop.
+/// <seealso href="https://elmish.github.io/elmish/#dispatch-loop" />
+/// </summary>
 type Dispatch<'msg> = 'msg -> unit
 
-/// Subscription - return immediately, but may schedule dispatch of a message at any time
+/// <summary>
+/// A function that returns immediately, but may schedule dispatch of one or multiple Messages at any time
+/// via its access to a Dispatch function.
+/// This is an abstraction over raw Messages passed along to the MVU processing loop
+/// necessary to deal with real-world scenarios in which Effect functions may take a while to complete.
+/// This models an Elm "side-effect" like in
+/// <seealso href="https://elmish.github.io/elmish/#tasks-and-side-effects" />
+/// or
+/// <seealso href="https://elmprogramming.com/side-effects.html" />
+/// </summary>
 type Effect<'msg> = Dispatch<'msg> -> unit
 
-/// Cmd - container for effects that may produce messages
+/// <summary>
+/// A list of Effects that may dispatch Messages;
+/// the carriers of instructions you issue from the init and update functions.
+/// See
+/// <seealso href="https://elmish.github.io/elmish/#commands" />
+/// </summary>
 type Cmd<'msg> = Effect<'msg> list
 
-/// Cmd module for creating and manipulating commands
+/// A module for creating and manipulating Commands
+/// with a Command being a list of Message-dispatching Effects you issue from the init and update functions
+/// and an Effect being a function with access to a Dispatch function receiving a Message.
 [<RequireQualifiedAccess>]
 module Cmd =
     /// Execute the commands using the supplied dispatcher
@@ -24,32 +43,48 @@ module Cmd =
             with ex ->
                 onError ex)
 
-    /// None - no commands, also known as `[]`
+    /// No command; an empty list of Message-dispatching Effects equivalent to `[]`.
+    /// For when you don't want to issue a Command.
     let none: Cmd<'msg> = []
 
-    /// When emitting the message, map to another type
+    /// <summary>
+    /// Converts a Command of type 'a into a Command of type 'msg.
+    /// This is useful for emitting Commands of a uniform type,
+    /// like when receiving child messages in a parent-child composition scenario. See
+    /// <seealso href="https://elmish.github.io/elmish/docs/parent-child.html" />
+    /// </summary>
     let map (f: 'a -> 'msg) (cmd: Cmd<'a>) : Cmd<'msg> =
         cmd |> List.map(fun g -> (fun dispatch -> f >> dispatch) >> g)
 
-    /// Aggregate multiple commands
+    /// <summary>
+    /// Concatenates the Effects of multiple Commands into one list.
+    /// Use for emitting multiple Commands at the same time from the init or update function.
+    /// E.g. in an parent-child composition scenario:
+    /// <seealso href="https://elmish.github.io/elmish/docs/parent-child.html" />
+    /// </summary>
     let batch (cmds: Cmd<'msg> list) : Cmd<'msg> = List.concat cmds
 
-    /// Command to call the effect
+    /// <summary>
+    /// Returns a command to call a custom Effect function with access to a Dispatch function.
+    /// Use for example to dispatch status updates or yield partial results from long-running background tasks.
+    /// </summary>
     let ofEffect (effect: Effect<'msg>) : Cmd<'msg> = [ effect ]
 
-    /// Command to issue a specific message
+    /// Command to issue a specific message.
+    /// Wraps the message into the Command structure returned from the update and init functions.
     let ofMsg (msg: 'msg) : Cmd<'msg> = [ fun dispatch -> dispatch msg ]
 
-    /// Command to issue a specific message, only when Option.IsSome = true
+    /// Command to issue the message from the message option if Option.IsSome
     let ofMsgOption (msg: 'msg option) : Cmd<'msg> =
         [ fun dispatch ->
               match msg with
               | None -> ()
               | Some msg -> dispatch msg ]
 
+    /// Creates Commands from the return values and/or exceptions of simple functions,
+    /// wrapping the call in a try/with statement. Use this to deal with code that may throw exceptions.
     module OfFunc =
-        /// Command to evaluate a simple function and map the result
-        /// into success or error (of exception)
+        /// Creates a Command to evaluate a simple function and map either the return value or exception to a message
         let either (task: 'a -> _) (arg: 'a) (ofSuccess: _ -> 'msg) (ofError: _ -> 'msg) : Cmd<'msg> =
             let bind dispatch =
                 try
@@ -59,7 +94,7 @@ module Cmd =
 
             [ bind ]
 
-        /// Command to evaluate a simple function and map the success to a message
+        /// Creates a Command to evaluate a simple function and map the return value to a message
         /// discarding any possible error
         let perform (task: 'a -> _) (arg: 'a) (ofSuccess: _ -> 'msg) : Cmd<'msg> =
             let bind dispatch =
@@ -70,7 +105,8 @@ module Cmd =
 
             [ bind ]
 
-        /// Command to evaluate a simple function and map the error (in case of exception)
+        /// Creates a Command to evaluate a simple function returning unit
+        /// and map the error (in case of exception) to a message
         let attempt (task: 'a -> unit) (arg: 'a) (ofError: _ -> 'msg) : Cmd<'msg> =
             let bind dispatch =
                 try
@@ -80,6 +116,9 @@ module Cmd =
 
             [ bind ]
 
+    /// Internal module for building Commands from the return values or exceptions of Async functions
+    /// using Async.Catch like an async try/with statement.
+    /// You'll probably want to use either of the modules OfAsync or OfAsyncImmediate instead of this.
     module OfAsyncWith =
         /// Command that will evaluate an async block and map the result
         /// into success or error (of exception)
@@ -98,6 +137,7 @@ module Cmd =
             [ bind >> start ]
 
         /// Command that will evaluate an async block and map the success
+        /// discarding any possible error
         let perform (start: Async<unit> -> unit) (task: 'a -> Async<_>) (arg: 'a) (ofSuccess: _ -> 'msg) : Cmd<'msg> =
             let bind dispatch =
                 async {
@@ -136,6 +176,10 @@ module Cmd =
 
             [ bind >> start ]
 
+    /// For building Commands from Async functions queued to be run in the background, started on a thread pool thread using Async.Start.
+    /// Suitable for long-running or CPU-bound computations where you want to free up the UI thread to remain responsive to do other work.
+    /// See https://learn.microsoft.com/en-us/dotnet/fsharp/tutorials/async#asyncstart
+    /// and https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/async-padl-revised-v2.pdf page 5.
     module OfAsync =
         /// Command that will evaluate an async block and map the result
         /// into success or error (of exception)
@@ -150,12 +194,18 @@ module Cmd =
         let inline attempt (task: 'a -> Async<_>) (arg: 'a) (ofError: _ -> 'msg) : Cmd<'msg> =
             OfAsyncWith.attempt Async.Start task arg ofError
 
+        /// Command that will evaluate an async block and map the success 'msg
         let inline msg (task: Async<'msg>) =
             OfAsyncWith.perform Async.Start (fun () -> task) () id
 
+        /// Command that will evaluate an async block and map the success 'msg Option.Value if Option.IsSome
         let inline msgOption (task: Async<'msg option>) =
             OfAsyncWith.performOption Async.Start (fun () -> task) () id
 
+    /// For building Commands from Async functions started immediately on the current operating system thread
+    /// using Async.StartImmediate. This is helpful if you need to update something on the calling thread during the computation.
+    /// For example if an asynchronous computation must update a UI (such as updating a progress bar).
+    /// See https://learn.microsoft.com/en-us/dotnet/fsharp/tutorials/async#asyncstartimmediate
     module OfAsyncImmediate =
         /// Command that will evaluate an async block and map the result
         /// into success or error (of exception)
@@ -170,21 +220,27 @@ module Cmd =
         let inline attempt (task: 'a -> Async<_>) (arg: 'a) (ofError: _ -> 'msg) : Cmd<'msg> =
             OfAsyncWith.attempt Async.StartImmediate task arg ofError
 
+    /// <summary>
+    /// For building Commands from executing ("hot") .NET Tasks using Async.AwaitTask.
+    /// <seealso href="https://learn.microsoft.com/en-us/dotnet/fsharp/tutorials/async#core-concepts" />
+    /// </summary>
     module OfTask =
-        /// Command to call a task and map the results
+        /// Command to map both the success and possible error result of a Task
         let inline either (task: 'a -> Task<_>) (arg: 'a) (ofSuccess: _ -> 'msg) (ofError: _ -> 'msg) : Cmd<'msg> =
             OfAsync.either (task >> Async.AwaitTask) arg ofSuccess ofError
 
-        /// Command to call a task and map the success
+        /// Command to map the success result of a Task
         let inline perform (task: 'a -> Task<_>) (arg: 'a) (ofSuccess: _ -> 'msg) : Cmd<'msg> =
             OfAsync.perform (task >> Async.AwaitTask) arg ofSuccess
 
-        /// Command to call a task and map the error
+        /// Command to map the error of a Task without a success result
         let inline attempt (task: 'a -> #Task) (arg: 'a) (ofError: _ -> 'msg) : Cmd<'msg> =
             OfAsync.attempt (task >> Async.AwaitTask) arg ofError
 
+        /// Command to map the success 'msg returned from a Task
         let inline msg (task: Task<'msg>) = OfAsync.msg(task |> Async.AwaitTask)
 
+        /// Command to map the success 'msg Option.Value returned from a Task if Option.IsSome
         let inline msgOption (task: Task<'msg option>) =
             OfAsync.msgOption(task |> Async.AwaitTask)
 
diff --git a/src/Fabulous/Program.fs b/src/Fabulous/Program.fs
@@ -6,9 +6,11 @@ open System.Diagnostics
 /// Configuration of the Fabulous application
 type Program<'arg, 'model, 'msg> =
     {
-        /// Give the initial state for the application
+        /// Returns the initial model/state of the application and an intial Command
         Init: 'arg -> 'model * Cmd<'msg>
-        /// Update the application state based on a message
+        /// Returns a new model/application state
+        /// updated from a message applied to the current model
+        /// and optionally another Command
         Update: 'msg * 'model -> 'model * Cmd<'msg>
         /// Add a subscription that can dispatch messages
         Subscribe: 'model -> Sub<'msg>
@@ -22,7 +24,7 @@ type Program<'arg, 'model, 'msg> =
 type Program<'arg, 'model, 'msg, 'marker> =
     {
         State: Program<'arg, 'model, 'msg>
-        /// Render the application state
+        /// Renders the model/application state
         View: 'model -> WidgetBuilder<'msg, 'marker>
         /// Indicates if a previous Widget's view can be reused
         CanReuseView: Widget -> Widget -> bool
@@ -50,6 +52,12 @@ module ProgramDefaults =
         Trace.WriteLine(String.Format("Unhandled exception: {0}", exn.ToString()), "Debug")
         false
 
+/// <summary>
+/// A module for building and configuring Elm programs using an MVU loop.
+/// See also
+/// <seealso href="https://docs.fabulous.dev/advanced/composing-larger-applications/splitting-into-independent-mvu-states" />
+/// <seealso href="https://docs.fabulous.dev/basics/mvu" />
+/// </summary>
 module Program =
     let inline private define (init: 'arg -> 'model * Cmd<'msg>) (update: 'msg -> 'model -> 'model * Cmd<'msg>) =
         { Init = init
@@ -58,21 +66,50 @@ module Program =
           Logger = ProgramDefaults.defaultLogger()
           ExceptionHandler = ProgramDefaults.defaultExceptionHandler }
 
-    /// Create a program using an MVU loop
+    /// <summary>
+    /// Creates a simple stateful, side-effect-free Program using an MVU loop.
+    /// The init function takes an input 'arg and returns a 'model representing the initial state,
+    /// the update function receives a 'msg and a 'model and returns an updated 'model.
+    /// See the upper diagram in <seealso href="https://elmprogramming.com/elm-architecture-conclusion.html" />
+    /// </summary>
     let stateful (init: 'arg -> 'model) (update: 'msg -> 'model -> 'model) =
         define (fun arg -> init arg, Cmd.none) (fun msg model -> update msg model, Cmd.none)
 
-    /// Create a program using an MVU loop
+    /// <summary>
+    /// Creates a stateful Program using an MVU loop that supports side-effects
+    /// - by both the init and update functions returning not only a 'model,
+    /// but an additional Cmd{'msg} alongside it.
+    /// This is an abstraction of a list of Effect{'msg} functions that return immediatly,
+    /// but may dispatch zero or many additional messages when given a Dispatch{'msg} function.
+    /// The Cmd{'msg} is fed into the MVU loop for processing of the side-effects by supplying them with a dispatch.
+    /// Note that the Cmd{'msg} may not only wrap (async) side-effects,
+    /// but also simple messages (using Cmd.ofMsg) or even be an empty list (using Cmd.none) .
+    /// See the lower diagram in <seealso href="https://elmprogramming.com/elm-architecture-conclusion.html" />
+    /// </summary>
     let statefulWithCmd (init: 'arg -> 'model * Cmd<'msg>) (update: 'msg -> 'model -> 'model * Cmd<'msg>) = define init update
 
-    /// Create a program using an MVU loop. Add support for CmdMsg
+    /// <summary>
+    /// Creates a Program using an MVU loop supporting isolated side-effects.
+    /// This is similar to statefulWithCmd, but instead of directly returning a Cmd{'msg}
+    /// (which may wrap a side-effect like a network or DB call),
+    /// the init and update functions return a simple 'cmdMsg list - making them pure and easy to test.
+    /// This will require you to add an additional discriminated union type for 'cmdMsg to your Program
+    /// with a case representing each side-effect.
+    /// An additional mapCmd function maps a 'cmdMsg back to the intended side-effect.
+    /// </summary>
     let statefulWithCmdMsg (init: 'arg -> 'model * 'cmdMsg list) (update: 'msg -> 'model -> 'model * 'cmdMsg list) (mapCmd: 'cmdMsg -> Cmd<'msg>) =
         let mapCmds cmdMsgs = cmdMsgs |> List.map mapCmd |> Cmd.batch
         define (fun arg -> let m, c = init arg in m, mapCmds c) (fun msg model -> let m, c = update msg model in m, mapCmds c)
 
-    /// Subscribe to external source of events, overrides existing subscription.
-    /// Return the subscriptions that should be active based on the current model.
-    /// Subscriptions will be started or stopped automatically to match.
+    /// <summary>
+    /// Subscribe the program to an external source of events represented by the subscribe function, overriding existing subscriptions.
+    /// The subscribe function should return the subscriptions that should be active based on the supplied model.
+    /// Subscriptions will be started or stopped accordingly.
+    /// See also
+    /// <seealso href="https://docs.fabulous.dev/basics/application-state/commands#triggering-commands-from-external-events" />
+    /// <seealso href="https://elmprogramming.com/subscriptions.html" />
+    /// <seealso href="https://elmish.github.io/elmish/docs/subscriptionv3.html" />
+    /// </summary>
     let withSubscription (subscribe: 'model -> Sub<'msg>) (program: Program<'arg, 'model, 'msg>) = { program with Subscribe = subscribe }
 
     /// Map existing subscription to external source of events.
diff --git a/src/Fabulous/Sub.fs b/src/Fabulous/Sub.fs
@@ -2,10 +2,12 @@ namespace Fabulous
 
 open System
 
-/// SubId - Subscription ID, alias for string list
+/// Subscription ID, alias for string list
 type SubId = string list
 
-/// Subscribe - Starts a subscription, returns IDisposable to stop it
+/// Starts a subscription by supplying a Dispatch{'msg}
+/// which it may use to start dispatching messages similar to Effect{'msg}.
+/// Returns an IDisposable to stop it.
 type Subscribe<'msg> = Dispatch<'msg> -> IDisposable
 
 /// Subscription - Generates new messages when running
