You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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
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:
Not any kind of blocker, just docs improvements that we should make at some point.
cc @sffc
The text was updated successfully, but these errors were encountered: