Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Allow user-set ids for xmldoc example nodes #704

Merged
merged 3 commits into from
Oct 30, 2021
Merged

Allow user-set ids for xmldoc example nodes #704

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f238b8e
Allow user-set ids for xmldoc example nodes
baronfel Sep 8, 2021
a687465
actually render example ids in the htmldoc
baronfel Sep 8, 2021
32db236
tests
baronfel Sep 14, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 13 additions & 2 deletions src/FSharp.Formatting.ApiDocs/GenerateModel.fs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,13 @@ module internal Utils =
module Html =
let sepWith s l = l |> List.sepWith (!! s) |> span []

type System.Xml.Linq.XElement with
member x.TryAttr (attr: string) =
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added this for convenience and then only used it in the new code, but I'd of course be willing to reuse it in the existing attribute fetches in this file if you like.

let a = x.Attribute (XName.Get attr)
if a = null then None
else if String.IsNullOrEmpty a.Value then None
else Some a.Value

/// Represents some HTML formatted by model generation
type ApiDocHtml(html: string) =

Expand Down Expand Up @@ -1560,8 +1567,12 @@ module internal SymbolReader =
let exampleNodes = doc.Elements(XName.Get "example") |> Seq.toList
[ for (id, e) in List.indexed exampleNodes do
let html = new StringBuilder()
let n = if id = 0 then "example" else "example-" + string id
rawData.[n] <- e.Value
let exampleId =
match e.TryAttr "id" with
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tied to the question in the RFC change, what level of uniqueness should be enforced by tooling?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ideally fail if --strict is used, and warn otherwise

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm noodling around the implementation a bit here still for validation purposes: if the scope is just within a particular example then that's easy to do validation on, because we have all the examples locally, but at any other scope than that things get hard because we don't have that data available and/or we'd have to push the validation up a level...

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

settled on duplicate within a member at the moment, but we could expand that to the type semi-easily if desired

| None ->
if id = 0 then "example" else "example-" + string id
| Some attrId -> attrId
rawData.[exampleId] <- e.Value
readXmlElementAsHtml true urlMap cmds html e
ApiDocHtml(html.ToString()) ]

Expand Down