-
Notifications
You must be signed in to change notification settings - Fork 790
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
Sorted the string.fsi entries and added examples to each one #12130
Conversation
Adding a link to the meta-issue for tracking. Thanks for submitting these! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is a fantastic start - the examples are really well chosen.
Have left some comments - could you aplpy them systematically and I'll review again ?
src/fsharp/FSharp.Core/string.fsi
Outdated
/// | ||
/// <returns>The concatenated string.</returns> | ||
/// | ||
/// <example> The following samples shows how to interspace spaces in a text |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is actually the first time I've seen multiple examples in the wild, so congratulations on surprising me :)
I did check, and FSharp.Formatting and FsAutoComplete do handle multiple examples just fine, so this shouldn't be a problem from the perspective of tooling consuming these docs.
@dsyme it does make me want some kind of 'example identifier' for use in generation, for example generating a link of FSharp.Core.StringModule#collect-example-collect-space
in order to jump to the specific example, but that's just some off-the-cuff musing. (FSharp.Formatting already generates a numeric identifier for this case, but something more stable might be useful?)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@dsyme it does make me want some kind of 'example identifier' for use in generation, for example generating a link of FSharp.Core.StringModule#collect-example-collect-space in order to jump to the specific example, but that's just some off-the-cuff musing. (FSharp.Formatting already generates a numeric identifier for this case, but something more stable might be useful?)
Makes sense, yes, even just collect-example-1
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
just use <example id="collect-whatever">
I think
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I did check, and FSharp.Formatting and FsAutoComplete do handle multiple examples just fine, so this shouldn't be a problem from the perspective of tooling consuming these docs.
Thank you for checking this!!!!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yeah, that's what I was getting at, I just wonder if it's worth codifying that in the tooling RFC and adding support to FSharp.Formatting then.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yeah, that's what I was getting at, I just wonder if it's worth codifying that in the tooling RFC and adding support to FSharp.Formatting then.
Absolutely
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
tracking this on the RFC and in FSharp.Formatting
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Added ids to every example tag
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Facepalm, I get it now: you want to generate the ids ... . I should remove them then?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
no, I'd keep them. My intent was for the author to give them meaningful ids. There is some last-chance id generation happening in FSharp.Formatting, but the MR I have up now always takes the id
that is present if there is one. So, all in all, I think what you have now is great 👍
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've left some comments/improvements - I'll merge and could you address them on next PR? Thanks
/// <code lang="fsharp"> | ||
/// let input = "Hello" | ||
/// input |> String.iteri (fun i c -> printfn "%d. %c %d" (i + 1) c (int c)) | ||
/// // evaluates unit |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think these english language parts should not be in <code>
/// | ||
/// <example id="init-example-1"> Enumerate digits ASCII codes | ||
/// <code lang="fsharp"> | ||
/// String.init 10 (fun i -> int '0' + i |> sprintf "%d ") // evaluates "48 49 50 51 52 53 54 55 56 57 " |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
These lines are getting too long I think (102 characters), suggest a maximum of 80 with a preference for 60
/// <code lang="fsharp">
/// String.init 10 (fun i -> int '0' + i |> sprintf "%d ")
/// </code>
/// evaluates to
/// <code>
/// "48 49 50 51 52 53 54 55 56 57 "
/// </code>
across all the samples.
/// <code lang="fsharp"> | ||
/// let input = "Hello" | ||
/// input |> String.iter (fun c -> printfn "%c %d" c (int c)) | ||
/// // evaluates unit |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
English language parts outside of <code>
No description provided.