Add missing doc comments

build.fsx

@@ -102,6 +102,7 @@ Target.create "tags" (fun _ ->
             let childrenArg = if tag.CanHaveChildren then " (children: list<Node>)" else ""
             let childrenVal = if tag.CanHaveChildren then "children" else "[]"
             s.AppendLine(sprintf """/// Create an HTML `<%s>` element.""" tag.Name)
+             .AppendLine(        """/// [category: HTML tag names]""")
              .AppendLine(sprintf """let %s (attrs: list<Attr>)%s : Node =""" ident childrenArg)
              .AppendLine(sprintf """    elt "%s" attrs %s""" tag.Name childrenVal)
              .AppendLine()

src/Bolero.Server/Remoting.fs

@@ -34,20 +34,28 @@ open Bolero
 open Bolero.Remoting
 open System.Text
 
+/// [omit]
 type IRemoteHandler =
     abstract Handler : IRemoteService
 
+/// [omit]
 [<AbstractClass>]
 type RemoteHandler<'T when 'T :> IRemoteService>() =
     abstract Handler : 'T
     interface IRemoteHandler with
         member this.Handler = this.Handler :> IRemoteService
 
+/// The context to inject in a remote service to authorize remote functions.
 type IRemoteContext =
     inherit IHttpContextAccessor
+
+    /// Indicate that a remote function is only available to authenticated users.
     abstract Authorize<'req, 'resp> : ('req -> Async<'resp>) -> ('req -> Async<'resp>)
+
+    /// Indicate that a remote function is available to users that match the given requirements.
     abstract AuthorizeWith<'req, 'resp> : seq<IAuthorizeData> -> ('req -> Async<'resp>) -> ('req -> Async<'resp>)
 
+/// [omit]
 type RemoteContext(http: IHttpContextAccessor, authService: IAuthorizationService, authPolicyProvider: IAuthorizationPolicyProvider) =
 
     let authorizeWith authData f =
@@ -146,6 +154,7 @@ type internal ServerRemoteProvider(services: seq<RemotingService>) =
         member this.GetService<'T when 'T :> IRemoteService>() =
             this.GetService<'T>()
 
+/// Extension methods to enable support for remoting in the ASP.NET Core server side.
 [<Extension>]
 type ServerRemotingExtensions =
 
@@ -162,30 +171,37 @@ type ServerRemotingExtensions =
             let basePath = basePath handler
             RemotingService(basePath, typeof<'T>, handler))
 
+    /// Add a remote service at the given path.
     [<Extension>]
     static member AddRemoting<'T when 'T : not struct>(this: IServiceCollection, basePath: PathString, handler: IRemoteContext -> 'T) =
         ServerRemotingExtensions.AddRemotingImpl<'T>(this, (fun _ -> basePath), handler)
 
+    /// Add a remote service at the given path.
     [<Extension>]
     static member AddRemoting<'T when 'T : not struct>(this: IServiceCollection, basePath: PathString, handler: 'T) =
         ServerRemotingExtensions.AddRemotingImpl<'T>(this, (fun _ -> basePath), (fun _ -> handler))
 
+    /// Add a remote service at the given path.
     [<Extension>]
     static member AddRemoting<'T when 'T : not struct>(this: IServiceCollection, basePath: string, handler: IRemoteContext -> 'T) =
         ServerRemotingExtensions.AddRemotingImpl<'T>(this, (fun _ -> PathString basePath), handler)
 
+    /// Add a remote service at the given path.
     [<Extension>]
     static member AddRemoting<'T when 'T : not struct>(this: IServiceCollection, basePath: string, handler: 'T) =
         ServerRemotingExtensions.AddRemotingImpl<'T>(this, (fun _ -> PathString basePath), (fun _ -> handler))
 
+    /// Add a remote service.
     [<Extension>]
     static member AddRemoting<'T when 'T : not struct and 'T :> IRemoteService>(this: IServiceCollection, handler: IRemoteContext -> 'T) =
         ServerRemotingExtensions.AddRemotingImpl<'T>(this, (fun h -> PathString h.BasePath), handler)
 
+    /// Add a remote service.
     [<Extension>]
     static member AddRemoting<'T when 'T : not struct and 'T :> IRemoteService>(this: IServiceCollection, handler: 'T) =
         ServerRemotingExtensions.AddRemotingImpl<'T>(this, (fun h -> PathString h.BasePath), (fun _ -> handler))
 
+    /// Add a remote service using dependency injection.
     [<Extension>]
     static member AddRemoting<'T when 'T : not struct and 'T :> IRemoteHandler>(this: IServiceCollection) =
         ServerRemotingExtensions.AddRemotingImpl(this.AddSingleton<'T>(), fun services ->

src/Bolero.Templating.Provider/Provider.fs

@@ -36,10 +36,9 @@ type Template (cfg: TypeProviderConfig) as this =
 
     do try
         let templateTy = ProvidedTypeDefinition(thisAssembly, rootNamespace, "Template", None, isErased = false)
-        templateTy.DefineStaticParameters(
-            [
-                ProvidedStaticParameter("pathOrHtml", typeof<string>)
-            ], fun typename pars ->
+        let sp = ProvidedStaticParameter("pathOrHtml", typeof<string>)
+        sp.AddXmlDoc("The path to an HTML file, or an HTML string directly.")
+        templateTy.DefineStaticParameters([sp], fun typename pars ->
             let asm = ProvidedAssembly()
             match pars with
             | [| :? string as pathOrHtml |] ->
@@ -51,6 +50,9 @@ type Template (cfg: TypeProviderConfig) as this =
                 ty
             | x -> failwithf "Unexpected parameter values: %A" x
         )
+        templateTy.AddXmlDoc("\
+            Provide content from a template HTML file.\n\
+            [category: HTML]")
         this.AddNamespace(rootNamespace, [templateTy])
         with exn ->
             // Put the full error, including stack, in the message

src/Bolero/Cmd.fs

@@ -28,6 +28,7 @@ open Microsoft.JSInterop
 open Elmish
 open Bolero.Remoting
 
+/// Elmish commands for Async and Task jobs, remote calls and JavaScript interop.
 module Cmd =
 
     // This should be in Elmish really.

src/Bolero/Components.fs

@@ -29,7 +29,8 @@ open Microsoft.JSInterop
 open Elmish
 open Bolero.Render
 
-/// A component built from `Html.Node`s.
+/// Base class for components built from `Bolero.Node`s.
+/// [category: Components]
 [<AbstractClass>]
 type Component() =
     inherit ComponentBase()
@@ -44,6 +45,8 @@ type Component() =
     /// The rendered contents of the component.
     abstract Render : unit -> Node
 
+/// Base class for components with a typed model.
+/// [category: Components]
 [<AbstractClass>]
 type Component<'model>() =
     inherit Component()
@@ -59,7 +62,8 @@ type Component<'model>() =
     default this.ShouldRender(oldModel, newModel) =
         not <| this.Equal oldModel newModel
 
-/// A component that is part of an Elmish view.
+/// Base class for components that are part of an Elmish view.
+/// [category: Components]
 [<AbstractClass>]
 type ElmishComponent<'model, 'msg>() =
     inherit Component<'model>()
@@ -85,6 +89,7 @@ type ElmishComponent<'model, 'msg>() =
         this.OldModel <- this.Model
         this.View this.Model this.Dispatch
 
+/// [omit]
 type LazyComponent<'model,'msg>() =
     inherit ElmishComponent<'model,'msg>()
 
@@ -94,12 +99,15 @@ type LazyComponent<'model,'msg>() =
 
     override this.View model dispatch = this.ViewFunction model dispatch
 
+/// [omit]
 type IProgramComponent =
     abstract Services : System.IServiceProvider
 
+/// [omit]
 type Program<'model, 'msg> = Program<ProgramComponent<'model, 'msg>, 'model, 'msg, Node>
 
-/// A component that runs an Elmish program.
+/// Base class for components that run an Elmish program.
+/// [category: Components]
 and [<AbstractClass>]
     ProgramComponent<'model, 'msg>() =
     inherit Component<'model>()
@@ -109,15 +117,21 @@ and [<AbstractClass>]
     let mutable view = Node.Empty
     let mutable dispatch = ignore<'msg>
 
+    /// [omit]
     [<Inject>]
     member val NavigationManager = Unchecked.defaultof<NavigationManager> with get, set
+    /// [omit]
     [<Inject>]
     member val Services = Unchecked.defaultof<System.IServiceProvider> with get, set
+    /// The JavaScript interoperation runtime.
     [<Inject>]
     member val JSRuntime = Unchecked.defaultof<IJSRuntime> with get, set
+    /// [omit]
     [<Inject>]
     member val NavigationInterception = Unchecked.defaultof<INavigationInterception> with get, set
 
+    /// The component's dispatch method.
+    /// This property is initialized during the component's OnInitialized phase.
     member _.Dispatch = dispatch
     member val private Router = None : option<IRouter<'model, 'msg>> with get, set
 
@@ -207,10 +221,15 @@ and [<AbstractClass>]
             EventHandler<_> this.OnLocationChanged
             |> this.NavigationManager.LocationChanged.RemoveHandler
 
+/// A utility to bind a reference to a rendered HTML element.
+/// See https://fsbolero.io/docs/Blazor#html-element-references
+/// [category: HTML]
 type ElementReferenceBinder() =
 
     let mutable ref = Unchecked.defaultof<ElementReference>
 
+    /// The element reference.
+    /// This object must be bound using `Bolero.Html.attr.bindRef` before using this property.
     member _.Ref = ref
 
     member internal _.SetRef(r) = ref <- r