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

Make sure docs readers aren't confused by assert_writeable_eq #5905

Open
Manishearth opened this issue Dec 14, 2024 · 0 comments
Open

Make sure docs readers aren't confused by assert_writeable_eq #5905

Manishearth opened this issue Dec 14, 2024 · 0 comments
Milestone

Comments

@Manishearth
Copy link
Member

This came up in #5896, around to_parts specifically.

A lot of our doctests use assert_writeable_eq. This is great; it's relatively compact, and in as much as showing the user "the output of this function is this string" it does wonderfully.

However; almost no application code is going to be asserting the result of formatting. Most applications want a string or something. So someone seeing these docs may come away not actually knowing how to obtain what they want. Most of these types have a to_string() so it's not a huge deal when it comes to basic writing, but we could probably have more signposting especially around write_to_parts.

Various suggestions:

  • Make sure all writeable types have a to_string. I think we already do this.
  • Make sure the docs of the to_string mention Writeable, and mention that there's further functionality on that trait.
  • Code that supports parts-formatting should explicitly document it, and have a line or two linking to PartsWrite and such
  • assert_writeable_parts_eq should mention PartsWrite and write_to_parts explicitly.

Not any kind of blocker, just docs improvements that we should make at some point.

cc @sffc

@Manishearth Manishearth added this to the Utilities 1.0 milestone Dec 14, 2024
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

No branches or pull requests

1 participant