The examples for the API needs a common way to represent the results

[MecuSorin]

Taking Option.fold documentation example as an example you will notice that the output of the example is embedded as a code comment

There are cases where the sample together with the result are long enough to not make sense to be on the same line.

I am proposing 2 custom tags to be used inside the <code> tag:

• resulttoright (the purpose is to show a nice box with [ Evaluates: ][ "some result here" ])
• resultbelow (the purpose is to show a box underneath the code block

         [ Evaluates: ]
         [ "some 
             multiline | or just on line
             result" ])
  

As a way to have a visual cue use the edit issue in github, and imagine that the textarea is representing the code and the "status bar" with Attach files by dragging ... represents the resultbelow

[MecuSorin]

I assume that the magic happens here for html documentation?

[baronfel]

that's where the HTML is written, yeah, but the HTML to be written is parsed and generated in GenerateModel.fs. Take a look at related changes in my PR for how and where examples specifically are treated.

[baronfel]

I really like this idea in general because it opens the door to example-based tests of functions. Imagine a test suite that generates tests whose body is your example's code tag, and compares the final yielded result to the value in the expects tag or something inside the code block. Other ecosystems like Rust have this level of integration embedded and I think it's fantastic.

[MecuSorin]

See the captures for an argument for this https://github.com/fsprojects/FSharp.Formatting/issues/706