diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 0fc516cb3..794dfdb79 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -1,7 +1,13 @@ -## 7.2.7 +## 7.2.8 * [ApiDocs: examples not showing for types and modules](https://github.com/fsprojects/FSharp.Formatting/issues/599) +* Comma-separate interface list in API docs + +* Remove untyped Sections from ApiDocComment since individual supported sections are now available + +## 7.2.7 + * [ApiDocs: cref to members are not resolving to best possible link](https://github.com/fsprojects/FSharp.Formatting/issues/598) * [ApiDocs: namespace docs are showing in module/type summaries as well](https://github.com/fsprojects/FSharp.Formatting/issues/597) diff --git a/src/FSharp.Formatting.ApiDocs/GenerateHtml.fs b/src/FSharp.Formatting.ApiDocs/GenerateHtml.fs index 783a89d10..9c19a5401 100644 --- a/src/FSharp.Formatting.ApiDocs/GenerateHtml.fs +++ b/src/FSharp.Formatting.ApiDocs/GenerateHtml.fs @@ -206,19 +206,6 @@ type HtmlRender(model: ApiDocModel) = p [] [yield! sourceLink e.SourceLocation embed e.Comment.Summary; ] - match e.Comment.Remarks with - | Some r -> - p [Class "fsdocs-remarks"] [embed r] - | None -> () - - for e in e.Comment.Notes do - h5 [Class "fsdocs-note-header"] [!! "Note"] - p [Class "fsdocs-note"] [embed e] - - for e in e.Comment.Examples do - h5 [Class "fsdocs-example-header"] [!! "Example"] - p [Class "fsdocs-example"] [embed e] - ] ] ] @@ -238,7 +225,6 @@ type HtmlRender(model: ApiDocModel) = // Get all the members & comment for the type let entity = info.Entity let members = entity.AllMembers |> List.filter (fun e -> not e.IsObsolete) - let comment = entity.Comment // Group all members by their category let byCategory = @@ -246,7 +232,7 @@ type HtmlRender(model: ApiDocModel) = |> List.mapi (fun i (key, elems) -> let elems = elems |> List.sortBy (fun m -> m.Name) let name = if String.IsNullOrEmpty(key) then "Other module members" else key - (i, key, elems, name)) + (i, elems, name)) let usageName = match info.ParentModule with @@ -277,8 +263,11 @@ type HtmlRender(model: ApiDocModel) = match entity.AllInterfaces with | [] -> () | l -> - p [] [!! ("All Interfaces: ")] - ul [] [ for i in l -> li [] [embed i] ] + p [] [!! ("All Interfaces: ") + for (i, ity) in Seq.indexed l do + if i <> 0 then + !! ", " + embed ity ] if entity.Symbol.IsValueType then p [] [!! ("Kind: Struct")] @@ -300,21 +289,28 @@ type HtmlRender(model: ApiDocModel) = //if info.Entity.IsObsolete then // obsoleteMessage entity.ObsoleteMessage - div [Class "fsdocs-xmldoc" ] [ - // XML comment for the type has multiple sections that can be labelled - // with categories (to give comment for an individual category). Here, - // we print only those that belong to the - for sec in comment.Sections do - if not (byCategory |> List.exists (fun (_, g, _, _) -> g = sec.Key)) then - if (sec.Key <> "") then - h3 [] [encode(sec.Key)] - embed sec.Value - ] + // Show the summary (and sectioned docs without any members) + div [Class "fsdocs-xmldoc" ] [ embed entity.Comment.Summary ] + + // Show the remarks etc. + match entity.Comment.Remarks with + | Some r -> + p [Class "fsdocs-remarks"] [embed r] + | None -> () + + for note in entity.Comment.Notes do + h5 [Class "fsdocs-note-header"] [!! "Note"] + p [Class "fsdocs-note"] [embed note] + + for example in entity.Comment.Examples do + h5 [Class "fsdocs-example-header"] [!! "Example"] + p [Class "fsdocs-example"] [embed example] + if (byCategory.Length > 1) then // If there is more than 1 category in the type, generate TOC h3 [] [!!"Table of contents"] ul [] [ - for (index, _, _, name) in byCategory do + for (index, _, name) in byCategory do li [] [ a [Href (sprintf "#section%d" index)] [!! name ] ] ] @@ -332,18 +328,13 @@ type HtmlRender(model: ApiDocModel) = yield! renderEntities nestedEntities ] - for (index, key, ms, name) in byCategory do + for (index, ms, name) in byCategory do // Iterate over all the categories and print members. If there are more than one // categories, print the category heading (as

) and add XML comment from the type // that is related to this specific category. if (byCategory.Length > 1) then h2 [Id (sprintf "section%d" index)] [!! name] // 

- let info = comment.Sections |> Seq.tryFind(fun kvp -> kvp.Key = key) - match info with - | None -> () - | Some key -> - div [Class "fsdocs-xmldoc"] [ embed key.Value ] div [] (renderMembers "Functions and values" "Function or value" (ms |> List.filter (fun m -> m.Kind = ApiDocMemberKind.ValueOrFunction))) div [] (renderMembers "Type extensions" "Type extension" (ms |> List.filter (fun m -> m.Kind = ApiDocMemberKind.TypeExtension))) div [] (renderMembers "Active patterns" "Active pattern" (ms |> List.filter (fun m -> m.Kind = ApiDocMemberKind.ActivePattern))) diff --git a/src/FSharp.Formatting.ApiDocs/GenerateModel.fs b/src/FSharp.Formatting.ApiDocs/GenerateModel.fs index 5a948bb76..97580233b 100644 --- a/src/FSharp.Formatting.ApiDocs/GenerateModel.fs +++ b/src/FSharp.Formatting.ApiDocs/GenerateModel.fs @@ -80,52 +80,49 @@ module internal Utils = type ApiDocHtml(html: string) = /// Get the HTML text of the HTML section - member x.HtmlText = html + member _.HtmlText = html /// Represents a documentation comment attached to source code -type ApiDocComment(summary, remarks, parameters, returns, examples, notes, exceptions, sections, rawData) = +type ApiDocComment(summary, remarks, parameters, returns, examples, notes, exceptions, rawData) = /// The summary for the comment - member x.Summary : ApiDocHtml = summary + member _.Summary : ApiDocHtml = summary /// The remarks html for comment - member x.Remarks : ApiDocHtml option = remarks + member _.Remarks : ApiDocHtml option = remarks /// The param sections of the comment - member x.Parameters : (string * ApiDocHtml) list = parameters + member _.Parameters : (string * ApiDocHtml) list = parameters /// The examples sections of the comment - member x.Examples : ApiDocHtml list = examples + member _.Examples : ApiDocHtml list = examples /// The notes sections of the comment - member x.Notes : ApiDocHtml list = notes + member _.Notes : ApiDocHtml list = notes /// The return sections of the comment - member x.Returns : ApiDocHtml option = returns + member _.Returns : ApiDocHtml option = returns /// The notes sections of the comment - member x.Exceptions : (string * string option * ApiDocHtml) list = exceptions - - /// The parsed sections of the comment - member x.Sections : KeyValuePair list = sections + member _.Exceptions : (string * string option * ApiDocHtml) list = exceptions /// The raw data of the comment - member x.RawData: KeyValuePair list = rawData + member _.RawData: KeyValuePair list = rawData - static member internal Empty = ApiDocComment(ApiDocHtml(""), None, [], None, [], [], [], [], []) + static member internal Empty = ApiDocComment(ApiDocHtml(""), None, [], None, [], [], [], []) /// Represents a custom attribute attached to source code type ApiDocAttribute(name, fullName, constructorArguments, namedConstructorArguments) = /// The name of the attribute - member x.Name : string = name + member _.Name : string = name /// The qualified name of the attribute - member x.FullName : string = fullName + member _.FullName : string = fullName /// The arguments to the constructor for the attribute - member x.ConstructorArguments : obj list = constructorArguments + member _.ConstructorArguments : obj list = constructorArguments /// The named arguments for the attribute - member x.NamedConstructorArguments : (string*obj) list = namedConstructorArguments + member _.NamedConstructorArguments : (string*obj) list = namedConstructorArguments /// Gets a value indicating whether this attribute is System.ObsoleteAttribute member x.IsObsoleteAttribute = @@ -1359,14 +1356,8 @@ module internal SymbolReader = let examples = [ for e in examples -> ApiDocHtml(Literate.ToHtml(doc.With(paragraphs=e))) ] let returns = if returns.IsEmpty then None else Some (ApiDocHtml(Literate.ToHtml(doc.With(paragraphs=returns)))) - let sections = - [ for (k, v) in groups -> - let body = if k = "" then List.rev v else List.tail (List.rev v) - let html = ApiDocHtml(Literate.ToHtml(doc.With(body))) - KeyValuePair(k, html) ] - ApiDocComment(summary=summary, remarks=remarks, parameters=[], returns=returns, examples=examples, notes=notes, - exceptions=[], sections=sections, rawData=raw) + exceptions=[], rawData=raw) let findCommand cmd = match cmd with @@ -1568,11 +1559,10 @@ module internal SymbolReader = lst |> Seq.iteri (fun id el -> rawData.[n + "-" + string id] <- el.Value)) - let sections = [KeyValuePair("", summary)] let rawData = rawData |> Seq.toList let comment = ApiDocComment(summary=summary, remarks=remarks, parameters=parameters, returns=returns, - examples=examples, notes=notes, exceptions=exceptions, sections=sections, rawData=rawData) + examples=examples, notes=notes, exceptions=exceptions, rawData=rawData) comment, nsels let combineHtml (h1: ApiDocHtml) (h2: ApiDocHtml) = @@ -1593,7 +1583,6 @@ module internal SymbolReader = returns = combineHtmlOptions c1.Returns c2.Returns, notes = c1.Notes @ c2.Notes, exceptions = c1.Exceptions @ c2.Exceptions, - sections = c1.Sections @ c2.Sections, rawData = c1.RawData @ c2.RawData) let combineNamespaceDocs nspDocs =