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! |
dsyme
left a comment
dsyme
left a comment
There was a problem hiding this comment.
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.
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.
@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.
just use <example id="collect-whatever"> I think
There was a problem hiding this comment.
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.
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.
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.
Added ids to every example tag
There was a problem hiding this comment.
Facepalm, I get it now: you want to generate the ids ... . I should remove them then?
There was a problem hiding this comment.
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 👍
dsyme
left a comment
dsyme
left a comment
There was a problem hiding this comment.
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.
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.
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.
English language parts outside of <code>
4 participants
No description provided.