Allow automatic generation of function signature in function XML comments

cmdoffing commented 1 week ago

**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:

[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] 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
[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
[x] I have searched both open and closed suggestions on this site and believe this is not a duplicate

Please tick all that apply:

[x] 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 :+1: emoji on this issue. These counts are used to generally order the suggestions by engagement.

Tarmil commented 1 week ago

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?

vzarytovskii commented 1 week ago

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?

cmdoffing commented 1 week ago

My bad! I haven't used tooltips with my own XML docs. I didn't realize there was a separate mechanism being used to generate the signature in Visual Studio 2022, which I use. Thanks a lot for your rapid response and please close the request.

-- CMD

On Tue, Sep 10, 2024 at 5:10 AM Vlad Zarytovskii @.***> wrote:

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?

— Reply to this email directly, view it on GitHub https://github.com/fsharp/fslang-suggestions/issues/1384#issuecomment-2340103338, or unsubscribe https://github.com/notifications/unsubscribe-auth/AKLOHV3LCW6FAHJNHZMQBPTZV2ZQRAVCNFSM6AAAAABN5ZBSSCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDGNBQGEYDGMZTHA . You are receiving this because you authored the thread.Message ID: @.***>

fsharp / fslang-suggestions