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.

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

Support multiline XML documentation comments #783

Open
Happypig375 opened this issue Sep 21, 2019 · 4 comments

Comments

@Happypig375
Copy link
Contributor

commented Sep 21, 2019

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:

  • This is not a question (e.g. like one you might ask on stackoverflow) and I have searched stackoverflow for discussions of this issue
  • I have searched both open and closed suggestions on this site and believe this is not a duplicate
  • 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:

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

This comment has been minimized.

Copy link
Contributor Author

commented Sep 21, 2019

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

This comment has been minimized.

Copy link

commented Sep 21, 2019

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

This comment has been minimized.

Copy link
Member

commented Sep 21, 2019

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

This comment has been minimized.

Copy link

commented Sep 21, 2019

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 ;)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.