Documentation Overhaul #27
Conversation
| -- | 'fold_' keeps the return value of the left-folded bytestring. Useful for | ||
| -- simultaneous folds over a segmented bytestream. |
There was a problem hiding this comment.
I am not sure what "keeps" means here. It rather seems like the "return value" (r) is actually ignored. Perhaps you meant "transforms" rather than "keeps", since the (x -> b) argument is applied to the fold result.
Also "simultaneous" doesn't quite sound right either, I see this as rather "sequential". So this is just a fold over all the bytes, with the result then transformed via a final mapping?
There was a problem hiding this comment.
I'm going to trust the original wording, assuming that people who actually use the foldl library would understand this.
Co-authored-by: Viktor Dukhovni <viktor1ghub@dukhovni.org>
| @@ -713,8 +695,7 @@ putStrLn bs = hPut IO.stdout (snoc bs '\n') | |||
| -- , count | |||
| -- , count' | |||
|
|
|||
| {-| This will read positive or negative Ints that require 18 or fewer characters. | |||
| -} | |||
| -- | This will read positive or negative Ints that require 18 or fewer characters. | |||
There was a problem hiding this comment.
Don't know whether you subscribe to the haskell-cafe list, but in a post there today, I mentioned in passing that the readInt in this module is also egregiously slow. I got a 5x performance improvement when I wrote my own, and it entirely avoids the bogus 18-char limit, which is semantically dubious (wrong!) and cause overly long strings of decimals to parsed as multiple ints in successive calls to readInt for example.
So (likely a separate PR), we should replace readInt with something like my (not yet 100% polished) version...
|
Backticks do work to link symbols in Haddock. |
I did not know that, I've only seen single-quotes for that. Thanks for the note. I guess you can use whichever you prefer then, sorry about asking for these to be changed... |
|
No prob! I've using backticks for years so I was totally on autopilot when I added them all here. Pushing all your other suggestions up now... |
The
streamingecosystem is wonderful, but its public-facing documentation contains much content from its early days of experimentation. These explanations tend to be verbose and lack practical examples.This PR reworks this library's README and other relevant documentation to be more user friendly.
Docstring coverage is now also 100%.