Allow automatic generation of function signature in function XML comments
Opened this issue · 4 comments
**I propose we allow automatic generation of function signature in function XML comments.
/// Some function description comment.
/// <signature>
let f x y = ...
** The signature is the most important piece of documentation and it should be included. The existing way of approaching this problem in F# is to manually write out the signature. Doing this automatically ensures that we save time and get it right.
Pros and Cons
The advantages of making this adjustment to F# are better documentation and saved time.
The disadvantages of making this adjustment to F# are time to implement and an extra line in the function docs.
Extra information
Estimated cost (XS, S, M, L, XL, XXL):
S. Automatic signature generation is already done in FSI, so it should be an easy implementation.
Related suggestions: (put links to related suggestions here)
Affidavit (please submit!)
Please tick these items 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
- This is a language change and not purely a tooling change (e.g. compiler bug, editor support, warning/error messages, new warning, non-breaking optimisation) belonging to the compiler and tooling repository
- 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
- I have searched both open and closed suggestions on this site and believe this is not a duplicate
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
For Readers
If you would like to see this issue implemented, please click the 👍 emoji on this issue. These counts are used to generally order the suggestions by engagement.
Tooltips should be perfectly capable of displaying the signature without having to put it in the doc comment, manually or automatically. What editor are you using?
Tooltips should be perfectly capable of displaying the signature without having to put it in the doc comment, manually or automatically. What editor are you using?
Yeah, I second that. XML docs is usually complimentary to the signature in tooltips in tooling or used in the autogenerated documentation (like we have for fslib). What would be some examples when you need an additional signature in the xmldoc itself?
This does vaguely remind me of the perennial haskell style inline sigs generation suggestion. Basically the same as the FSI signatures file but placed prior to each function. The value is slightly low but it could be nice when you're trying to look at code in github.