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

improve doc comments for FSharp.Core #9844

Merged
merged 5 commits into from
Jul 31, 2020
Merged

improve doc comments for FSharp.Core #9844

merged 5 commits into from
Jul 31, 2020

Conversation

dsyme
Copy link
Contributor

@dsyme dsyme commented Jul 31, 2020

Continues the work of #9837 in a feature branch

There is an F# community effort going on to properly generate the FSharp.Core API docs using the fsdocs tooling, see

As part of this we will need to cleanup our XML doc in the original FSharp.Core source.

This PR will contain a bunch of improvements in this regard. I propose that doc improvements get pushed into feature/docs and we integrate them from time to time. Then for now the community docs for FSharp.Core can be built from fsharp/docs.

This batch of work includes:

  1. Add spacing between summary, param, exception, returns and remarks sections so it's much easier to visuall see what's what in the documentation. (currently it is hard to review and read in the source itself because it is cramped)

  2. Use <see cref="..."> more systematically - we already use this in seq.fsi so there is nothing new here, but this correctly adds the T: , P: and M: tags to the references.

  3. Remove a massive remarks section for the Printf module which is really written documentation, and has been transferred into the F# docs here: F# plaintext printing documentation docs#19632

See also #9805 which deals with possible improvements to the docs story where the compiler checks the docs including symbol references.

@KevinRansom KevinRansom merged commit be9280e into master Jul 31, 2020
@KevinRansom KevinRansom deleted the feature/docs branch July 31, 2020 22:01
@dsyme
Copy link
Contributor Author

dsyme commented Aug 1, 2020

@KevinRansom KevinRansom deleted the feature/docs branch 3 hours ago

Please leave this branch in existence, thanks (or we can give it another name). The CI for the repo https://github.com/fsharp/fsharp-core-api-docs will initially be set up to build directly from this branch. Once the docs are of high quality we will set it up to build multiple versions of the docs from a version tag.

I will set up auto-merge from master to feature/docs

abelbraaksma pushed a commit to abelbraaksma/fsharp that referenced this pull request Aug 9, 2020
* improve xml doc spacing

* improve cref nodes

* fix broken xml doc

* fix more crefs

* doc improvements
nosami pushed a commit to xamarin/visualfsharp that referenced this pull request Feb 23, 2021
* improve xml doc spacing

* improve cref nodes

* fix broken xml doc

* fix more crefs

* doc improvements
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants