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

Add support for the `example` documentation comment tag #769

Open
baronfel opened this issue Jul 12, 2019 · 4 comments

Comments

@baronfel
Copy link
Collaborator

commented Jul 12, 2019

Add support for the example documentation comment tag

I propose we add support for the example documentation comment tag as in C#: https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/example. This would allow library authors the provide inline samples for functions that could be surfaced in tooling such as extended tooltips or more detailed views like the Object Explorer in Visual Studio or the Info Panel in Ionide.

As a stretch, the code in such tags could even be typechecked in a way similar to Rust's example blocks:

Pros and Cons

The advantages of making this adjustment to F# are better 'defaults' available with less user effort. With examples attached to the functions themselves (and even moreso if those are typechecked) it's much more likely that a) documentation will exist at all for the function and b) that it remains in line with changes to the function over the course of editing.

The disadvantages of making this adjustment to F# are the amount of work it involves. Allowing for examples themselves (as just code samples that are in no way checked) I would estimate at an S or M, because it involves updating the documentation structures and passing that representation through to PDBs and FCS, but adding typechecking of them I would estimate at an M to L, primarily because of the work involved with assembling an accurate typecheck environment for each sample. Determining what symbols would be in scope for each typechecked example would be nontrivial.

Extra information

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

  • Just adding code examples: S/M
  • Typechecking those examples: M/L

Related suggestions: (put links to related suggestions here): None that I found

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
@dsyme

This comment has been minimized.

Copy link
Collaborator

commented Jul 17, 2019

@cartermp What do you think?

@smoothdeveloper

This comment has been minimized.

Copy link

commented Jul 17, 2019

My 2 cents, we may have two separate suggestions:

  • one to match the example xml doc tag in C#
  • one for the type checked blocks that could be surfaced / appended to the (existing or not) example tag

Work on the implementation in the compiler should be approached while keeping in mind retargetting the internal documentation representation to different supports / ecosystems is going to be important in the long term, ideally of course.

Supporting the first part in a near release seems kind of urgent to me, usage of that tag in C# for public APIs is pervasive enough to bring F# on par.

@cartermp

This comment has been minimized.

Copy link
Member

commented Jul 17, 2019

I'd love it.

@baronfel

This comment has been minimized.

Copy link
Collaborator Author

commented Jul 17, 2019

@smoothdeveloper I agree that I've conflated the two use cases, and I agree that at minimum is like to see examples be authorable and visible in documentation tools like the Object Explorer or Ionide Info Pane. I mostly mentioned them in the same suggestion because I want to help guide the expectation that typechecked examples are a thing we should do.

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