Discuss member panels

[dsyme]

Hi all,

I'd like to discuss the member panels (and the documentation for members more generally) coming out of FSharp.Formatting. I think it's good to do this in the context of FSharp.Core where we have relatively populated XML comments, though it's a more general FSharp.Formatting issue

For FSharp.Core a typical member panel looks like this:

Now, the things I'd like some help with are

1. Should the parameter types and the parameter descriptions be merged together? The F#F codebase is now getting to a point where it's cleaned up enough (and I understand it well enough) to allow this to happen. But what visuals do we want? Are there any really nice docs elsewhere integrating type information and documentation you can point me to?

2. Do we actually need to move to generating one page per member, especially when example usage starts being added? A library like PyTorch doesn't do this but of course MSDN does.

3. The left-right display of the member usage feels like wasted space. Perhaps each member should be stacked.

Here's an example of PyTorch (not necesarily great documentation though nor exemplar for FSHarp.Core)

Member list:

Member page:

The things I notice are:

• one page for each member

• vertical stacking

• types go in italics , parenthesized

• only summary text on member list page

[baronfel]

I definitely like the idea of generating more pages for members, though that definitely explodes the raw number of pages being generated. I also like the idea of being more proscriptive about grouping different types of members, for example lifting attributes or type extensions to a separate listing than records/unions/classes, and of course separating modules out entirely. The current long list of types/modules together doesn't really do a lot to guide me as a viewer of the docs.

[dsyme]

Hmmm interesting

Re entities - personally when I come to an API I want to know how to use it - I don't so much care if something is a type or a module. So something that shows the Map type next to the Map module feels right to me. There is some artificiality between many of these things in any case, So I'm not sure basic "kind" of entity is the right categorization. Kinds like "attribute" certainly are. There are also API-declared categorizations which F#F half supports today through somewhat baroque markdown comments.

The FSharp.Core namespace is definitely challenging and would be a good place to try to resurrect the categorization of entities (in xml docs though)

BTW there is now a project file setting UsesMarkdownComments which the F#F tooling respects. Better than having to supply it on the doc build line, as it can gradually become a standard if we persist with md comments.

Lists of members are also interesting. MSDN separates out properties but again the categorization feels a little artifical from a teaching point of view.

I'd like to work out how to collect more information on some if these things - eg, it's likely to be relevant to DiffSharp too.

I feel extension members should be categorised with the thing that is extended, with a note that an "open" is needed.

I'd also soon like to put work in to better displays for active patterns. Computation expression builders are very challenging however and really need hand written docs.

[dsyme]

that definitely explodes the raw number of pages being generated

It certainly would.... But then, with examples, it really is kind of necessary. I guess it should be an option - there's no point doing it if there's no meaningful content to show

[cartermp]

docs.microsoft.com does this for a few reasons:

• Examples can be larger, and pages shouldn't be too massive in general
• SEO for specific things can kick in
• Realistically you can't make everything 100% documented, so having dedicated pages lets you focus more on the most important ones

I think it's fine to have things as they are today but on docs.microsoft.com there will eventually be separate pages.

Separately, the fork of dotnet/docs also contains many, many F# samples for the core library that could be used: https://github.com/dotnet/docs/tree/master/samples/snippets/fsharp

Unfortunately most of them are horribly named from some pattern that was used in MSDN. I manually changed some of them but there's a lot of work to comb through them all.

[dsyme]

Separately, the fork of dotnet/docs also contains many, many F# samples for the core library that could be used: https://github.com/dotnet/docs/tree/master/samples/snippets/fsharp

Interesting. Where do those come from?

[cartermp]

Those were the old MSDN samples. Most are pretty good. They're fairly comprehensive as well, so we're not starting from 0 in terms of examples. But they need to be associated with the documentation.

[baronfel]

To some degree I'd say that these examples could be moved closer to the code, but I think that'll require us to implement support for the `example xmldoc tag

[dsyme]

I think <example> can be used, it's just ignored by F# Formatting. I'll fix that now

[jmhickman]

So as regards those snippets in the links above, what would be the best way to leverage or take advantage of them? Is there some specific process that could be applied, by hand or otherwise, that would make them ready for integration into something else?

[jmhickman]

Also, a couple of pennies in the opinion pile:
In general, I prefer a layout that is closer in form to the presented PyTorch example than the format currently used. That being said, as long as the content is informative and helps me understand something or solve my problem/answers my question, I kinda don't care so much what it looks like. The mainline Python documentation isn't strongly visually distinct, but it frequently answered my questions when I consulted it, so I regard it highly.