Support multiline XML documentation comments

[Happypig375]

Support multi-line XML documentation comments

I propose we support multi-line XML documentation comments

The existing way of approaching this problem in F# is using single-line XML documentation comments.

C

Single-line

/// <summary>Documentation</summary>
class C { }

Multi-line

/** <summary>Documentation</summary> */ class C { }

F

Single-line

/// Documentation
type C = A | B

Multi-line (Does not work currently, proposed to allow)

(** Documentation *) type C = A | B

Variations of usage:

(** Documentation *) type A = int * string
(** 1st line
2nd line *) type B = B of int
(**
2431258
9347356
7567527
3496303
5534504
2018472
*)
type Numbers = class end
(**
 * blah
 * bleh
 * blih
 * bloh
 * bluh
 * blyh
*)
type ``C#-style`` = struct end

Compare:

/// Documentation
type A = int * string
/// 1st line
/// 2nd line
type B = B of int
/// 2431258
/// 9347356
/// 7567527
/// 3496303
/// 5534504
/// 2018472
type Numbers = class end
/// blah
/// bleh
/// blih
/// bloh
/// bluh
/// blyh
type ``C#-style`` = struct end

Pros and Cons

The advantages of making this adjustment to F# are

1. Even more concise documentation
2. More usage of wasted horizontal space (for inline XML comments)
3. Informative text can be pasted in without needing to insert /// for each line
4. Documentation can be easily copied away
5. Parity with C#

The disadvantages of making this adjustment to F# are

1. Potential loss of uniformity of XML comments (/// usually is its own line)
2. New syntax to learn

Extra information

Estimated cost (XS, S, M, L, XL, XXL): S-M

Related suggestions: No

Affidavit (please submit!)

Please tick this by placing a cross in the box:

• [x] This is not a question (e.g. like one you might ask on stackoverflow) and I have searched stackoverflow for discussions of this issue
• [x] I have searched both open and closed suggestions on this site and believe this is not a duplicate
• [x] This is not something which has obviously "already been decided" in previous versions of F#. If you're questioning a fundamental design decision that has obviously already been taken (e.g. "Make F# untyped") then please don't submit it.

Please tick all that apply:

• [x] This is not a breaking change to the F# language design
• [x] I or my company would be willing to help implement and/or test this

[Happypig375]

Note: As a hack, the XML comment can technically be inlined by placing in end of previous line.

type A = class end /// Docs for B
type B = struct end /// Docs for I
type I = interface end

[abelbraaksma]

I think this would be a worthwhile addition. Though it's a matter of taste whether this is good coding practice (main argument against it, in the C# world, is that it disallows commenting out large chunks of code during development, which is probably why most tooling in C# auto inserts the single line comments), I think we should allow it.

As an aside, I think that the editor should insert the triple slash automatically upon a new line, just like with C#. This would make writing such documentation easier in the current situation.

[cartermp]

F# already supports multi-line XML doc comments:

/// <summary>
/// Documentation
/// </summary>
type C() = class end

It's worth calling out that the Java-ism that C# apparently supports automatically inserts a * on new lines though, so there's still clutter. Extending the OCAML-style comments in F# to also support XML doc tags seems generally fine, though I don't imagine it'll be a high priority.

[abelbraaksma]

F# already supports multi-line XML doc comments

I believe the OP meant that you wouldn't need to use single line comments to get multi line xml comments. But I could be wrong ;)

[dsyme]

Closing per reply https://github.com/fsharp/fslang-suggestions/issues/783#issuecomment-533809079

[Happypig375]

Extending the OCAML-style comments in F# to also support XML doc tags seems generally fine, though I don't imagine it'll be a high priority.

[dsyme]

Ha yes, no idea why I wrote that. Anyway no intention to support this, there's no need to have two ways to do xml docs.