Skip to content

Add pseudo code to compress*/expand* docs - #412

Merged
Shnatsel merged 2 commits into
linebender:mainfrom
RunDevelopment:compress-expand-docs
Oct 4, 2026
Merged

Shnatsel merged 2 commits into
linebender:mainfrom
RunDevelopment:compress-expand-docs

Conversation

@RunDevelopment

Copy link
Copy Markdown
Contributor

I couldn't understand what compress* and expand* were doing from their docs. (TBH, they had the kind of description that you only understand if you already know what it's doing.) So I added the algorithm these methods perform as pseudo code to the docs.

I opted for python-like pseudo code to save 2 lines of just closing braces.

@Shnatsel

Shnatsel commented Oct 4, 2026 •

Copy link
Copy Markdown
Contributor

I remember it being confusing and asking for doctests, but I guess it was never addressed and I overlooked it in the review. My bad!

I don't think the pseudocode is any more succinct than regular Rust. It adds the separate k = 0 initialization, and confuses matters by not being an actual language with pinned-down semantics. Intel also explains their intrinsics in pseudocode and I usually have trouble following that.

I think I'd like to see doctests/examples instead, because that's how std documents its functions and it's good to be consistent. If you feel doctests alone don't explain it, we can have both usage examples and an explanation of what this does in actual Rust.

@Shnatsel

Shnatsel commented Oct 4, 2026

Copy link
Copy Markdown
Contributor

Thank you for flagging this issue and for opening a PR, this should have been better documented from the start and it's my fault it wasn't done in the original PR.

@RunDevelopment

Copy link
Copy Markdown
Contributor Author

I made the pseudo code Rust as requested. (Not that anything of substance changed.)

I think I'd like to see doctests/examples instead, because that's how std documents its functions and it's good to be consistent.

This would be the first doctest of that kind. I don't intend to break that ground.

@Shnatsel

Shnatsel commented Oct 4, 2026

Copy link
Copy Markdown
Contributor

Fair enough about doctests. I messed around with them in #268 but didn't end up merging that and it might not be the best approach anyway.

Thank you!

@Shnatsel
Shnatsel added this pull request to the merge queue Oct 4, 2026
Merged via the queue into linebender:main with commit 02a29b3 Oct 4, 2026
23 checks passed
@RunDevelopment
RunDevelopment deleted the compress-expand-docs branch October 4, 2026 16:15
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