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

Use the strict/lazy type synonyms for better generated documentation #628

Merged
merged 1 commit into from
Nov 26, 2023

Conversation

MorrowM
Copy link
Contributor

@MorrowM MorrowM commented Nov 26, 2023

While using qualified names such as S.ByteString or L.ByteString
allows for GHC to disambiguate between the strict and lazy variants, the
generated haddocks end up being quite confusing, prime examples being
fromStrict and toStrict.

image

This patch replaces such uses with the type synonyms StrictByteString and LazyByteString to (hopefully) make the docs a bit clearer.

image

@Kleidukos
Copy link
Member

This indeed looks clearer! I envy the beginner who will learn Haskell with this change. :)

Copy link
Contributor

@Bodigrim Bodigrim left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder whether StrictByteString should remain just ByteString, but either way is fine for me.

@Bodigrim Bodigrim requested a review from clyring November 26, 2023 20:35
@MorrowM
Copy link
Contributor Author

MorrowM commented Nov 26, 2023

@Bodigrim The issue with doing that is that fromStrict and toStrict are exported in both Data.ByteString and Data.ByteString.Lazy. Possibly I could leave the doc comment as how it was, though.

Copy link
Member

@clyring clyring left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fantastic! I've wanted to do this for some time but never got around to it. I have a couple of very minor formatting questions/suggestions.

Thanks for doing this!

Data/ByteString/Builder/Internal.hs Outdated Show resolved Hide resolved
Data/ByteString/Builder/Internal.hs Outdated Show resolved Hide resolved
Data/ByteString/Builder/Internal.hs Outdated Show resolved Hide resolved
Data/ByteString/Builder/Internal.hs Outdated Show resolved Hide resolved
Data/ByteString/Builder/Internal.hs Outdated Show resolved Hide resolved
Data/ByteString/Builder/Internal.hs Outdated Show resolved Hide resolved
Data/ByteString/Builder/Internal.hs Outdated Show resolved Hide resolved
Data/ByteString/Builder/Internal.hs Outdated Show resolved Hide resolved
Data/ByteString/Lazy.hs Outdated Show resolved Hide resolved
Data/ByteString/Lazy/Internal/Deque.hs Show resolved Hide resolved
Replace confusing occurrences of strict/lazy ByteString in
generated documentation with the corresponding type
synonyms.
@MorrowM
Copy link
Contributor Author

MorrowM commented Nov 26, 2023

@clyring Thanks for the catches, I think I've fixed them all.

Copy link
Member

@clyring clyring left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

@clyring clyring merged commit 7e11412 into haskell:master Nov 26, 2023
0 of 3 checks passed
@clyring clyring added this to the 0.12.1.0 milestone Jan 30, 2024
clyring pushed a commit that referenced this pull request Jan 30, 2024
Replace confusing occurrences of strict/lazy ByteString in
generated documentation with the corresponding type
synonyms.

(cherry picked from commit 7e11412)
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.

4 participants