Suggestion: auto-expansion of `<details>…</details>` for direct links about fsharp.formatting

[nojaf]

My 2 cents: it would only make sense on pages with API docs and should not be part of the menu bar.

[nojaf]

Hmm, still some remaining problems with the new approach:

https://fsharp.github.io/fsharp-compiler-docs/reference/fsharp-compiler-codeanalysis-fsharpchecker.html#InvalidateAll

[nhirschey]

Something like this?

Yeah, exactly. To me that’s more intuitive.

[nojaf]

Sounds reasonable, go for it!

[brianrourkeboll]

@nojaf Hmm, I'll look.

Separately, I'm noticing else on that same page that will necessitate some additional tweaks in that area anyway.

The .fsdocs-entity-xmldoc { > div { flex-direction: row reverse } }, which was already there, affects the order of any paragraphs defined with <para> that are nested in the <summary>.

So these paragraphs —

/// <summary>
/// <para>
///   Parse and check a source code file, returning a handle to the results
/// </para>
/// <para>
///    Note: all files except the one being checked are read from the FileSystem API
/// </para>
/// <para>
///   Return FSharpCheckFileAnswer.Aborted if a parse tree was not available.
/// </para>
/// </summary>

— are shown in reverse order as

I think they should at least be shown in the order in which they're written, and it would probably be better if they were separated vertically instead of horizontally.

[nojaf]

Hmm, yeah, you're right. That row reverse was probably there for a reason. I'm okay with changing it, but we might need to consider any other issues it could introduce.

[brianrourkeboll]

Yeah, the contents themselves are generated in reverse order, only to be reversed again by the CSS, although I don't understand why:

FSharp.Formatting/src/FSharp.Formatting.ApiDocs/GenerateHtml.fs

Lines 183 to 189 in 56b856b

	let smry =
	div [ Class "fsdocs-summary" ] [
	yield! copyXmlSigIconForSymbolMarkdown m.Symbol
	yield! copyXmlSigIconForSymbol m.Symbol
	yield! sourceLink m.SourceLocation
	fsdocsSummary m.Comment.Summary
	]

[brianrourkeboll]

Hmm, still some remaining problems with the new approach:

https://fsharp.github.io/fsharp-compiler-docs/reference/fsharp-compiler-codeanalysis-fsharpchecker.html#InvalidateAll

Here's the explanation for this particular thing:

Sometimes the <div class="fsdocs-summary"> will be nested inside <details><summary>, and sometimes it won't be:

FSharp.Formatting/src/FSharp.Formatting.ApiDocs/GenerateHtml.fs

Lines 271 to 277 in 56b856b

	td [ Class "fsdocs-member-xmldoc" ] [
	if List.isEmpty dtls then
	smry
	elif String.IsNullOrWhiteSpace(m.Comment.Summary.HtmlText) then
	yield! dtls
	else
	details [] ((summary [] [ smry ]) :: dtls)

I removed the CSS for the bare div case in my PR, because I didn't understand that there were these different cases.

That conditional actually also means that, if there is no <summary> in the XML doc, there will be no source links, even if there are other elements:

I don't think there's a good reason not to show source links in such a case.

[brianrourkeboll]

If I did add an expand/collapse-all button, does this look like a reasonable place to put it? The idea would be for it to save your preference for the whole site to local storage, like the theme toggle.

expand-collapse.mp4

I guess it could also only be shown on pages that had API docs, but then would it still make sense to show it in the top right? Or somewhere else?

[nhirschey]

If it’s easy, to me it seems more intuitive on the same row as “instance members”. For me it doesn’t seem obvious to look for this on the menu bar. I expect expand/collapse to be located closer to the elements it affects.

(But if this does not appeal to you ignore it).

[brianrourkeboll]

@nhirschey

If it’s easy, to me it seems more intuitive on the same row as “instance members”. For me it doesn’t seem obvious to look for this on the menu bar. I expect expand/collapse to be located closer to the elements it affects.

Something like this?

expand-collapse-2.mp4

(Could also be with "Instance members" as you suggest instead of in the table header.)

[brianrourkeboll]

Implemented in #917, #919, #920.