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.

Sign up for GitHub

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

Jump to bottom

API Docs: fmt #29355

Closed
12 of 14 tasks
steveklabnik opened this issue Oct 26, 2015 · 12 comments
Closed
12 of 14 tasks

API Docs: fmt #29355

steveklabnik opened this issue Oct 26, 2015 · 12 comments
Labels
A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools C-tracking-issue Category: An issue tracking the progress of sth. like the implementation of an RFC E-help-wanted Call for participation: Help is requested to fix this issue. E-medium Call for participation: Medium difficulty. Experience needed to fix: Intermediate. E-mentor Call for participation: This issue has a mentor. Use #t-compiler/help on Zulip for discussion. P-medium Medium priority

Comments

@steveklabnik
Copy link
Member

steveklabnik commented Oct 26, 2015 •
edited
Loading

Part of #29329

http://doc.rust-lang.org/std/fmt/

Here's what needs to be done to close out this issue:

  • the module level docs almost belong in their own issue. These are very old docs written long ago, and while they're good, I have a hunch they could be made way better. Not needed to close this issue.
  • all of the traits should say "C formatting", where C is the char, rather than their current boilerplate. Except Write. And Display.
  • fmt::Result needs an example, showing off the use std::fmt; fmt::Result pattern.
  • write should have its Arguments section removed, we don't do this.
  • format has the same issue, and needs more explanation generally.
  • All of the traits have... I dunno, the wording feels awkward. This doesn't need to be fixed to close this issue, but would be nice.
  • Write needs a lot of links. and some examples.
  • Arguments needs examples, but also a justification of why this is all done this way.
  • DebugList should use the iterator boilerplate language, even though it's not an iterator. Mostly pointing to the docs of the function that creates it.
  • DebugMap same.
  • DebugSet same.
  • DebugStruct same.
  • DebugTuple same.
  • Error needs examples, and specifically use std::fmt; fmt::Error
  • Formatter should show where it's created, and talk about the details more.
@steveklabnik steveklabnik mentioned this issue Oct 26, 2015
Closed
51 tasks
@GuillaumeGomez GuillaumeGomez mentioned this issue Apr 21, 2016
Merged
steveklabnik added a commit to steveklabnik/rust that referenced this issue May 2, 2016
@steveklabnik
Rollup merge of rust-lang#33129 - GuillaumeGomez:fmt_doc, r=steveklabnik
0da788a 
Doc improvement on std::fmt module

Part of rust-lang#29355.

r? @steveklabnik
steveklabnik added a commit to steveklabnik/rust that referenced this issue May 5, 2016
@steveklabnik
Rollup merge of rust-lang#33129 - GuillaumeGomez:fmt_doc, r=steveklabnik
ced4a18 
Doc improvement on std::fmt module

Part of rust-lang#29355.

r? @steveklabnik
steveklabnik added a commit to steveklabnik/rust that referenced this issue May 5, 2016
@steveklabnik
Rollup merge of rust-lang#33129 - GuillaumeGomez:fmt_doc, r=steveklabnik
8f849df 
Doc improvement on std::fmt module

Part of rust-lang#29355.

r? @steveklabnik
steveklabnik added a commit to steveklabnik/rust that referenced this issue May 6, 2016
@steveklabnik
Rollup merge of rust-lang#33129 - GuillaumeGomez:fmt_doc, r=steveklabnik
0a14611 
Doc improvement on std::fmt module

Part of rust-lang#29355.

r? @steveklabnik
GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this issue May 7, 2016
@GuillaumeGomez
Rollup merge of rust-lang#33129 - GuillaumeGomez:fmt_doc, r=steveklabnik
143b423 
Doc improvement on std::fmt module

Part of rust-lang#29355.

r? @steveklabnik
Manishearth added a commit to Manishearth/rust that referenced this issue May 8, 2016
@Manishearth
Rollup merge of rust-lang#33129 - GuillaumeGomez:fmt_doc, r=steveklabnik
55fcf28 
Doc improvement on std::fmt module

Part of rust-lang#29355.

r? @steveklabnik
Manishearth added a commit to Manishearth/rust that referenced this issue May 9, 2016
@Manishearth
Rollup merge of rust-lang#33129 - GuillaumeGomez:fmt_doc, r=steveklabnik
dd20d66 
Doc improvement on std::fmt module

Part of rust-lang#29355.

r? @steveklabnik
Manishearth added a commit to Manishearth/rust that referenced this issue May 9, 2016
@Manishearth
Rollup merge of rust-lang#33129 - GuillaumeGomez:fmt_doc, r=steveklabnik
0fed5a8 
Doc improvement on std::fmt module

Part of rust-lang#29355.

r? @steveklabnik
steveklabnik added a commit to steveklabnik/rust that referenced this issue May 10, 2016
@steveklabnik
Rollup merge of rust-lang#33129 - GuillaumeGomez:fmt_doc, r=steveklabnik
b6b3b7b 
Doc improvement on std::fmt module

Part of rust-lang#29355.

r? @steveklabnik
steveklabnik added a commit to steveklabnik/rust that referenced this issue May 11, 2016
@steveklabnik
Rollup merge of rust-lang#33129 - GuillaumeGomez:fmt_doc, r=steveklabnik
c5e0099 
Doc improvement on std::fmt module

Part of rust-lang#29355.

r? @steveklabnik
@steveklabnik steveklabnik added the E-mentor Call for participation: This issue has a mentor. Use #t-compiler/help on Zulip for discussion. label Mar 8, 2017
@steveklabnik
Copy link
Member Author

I am happy to mentor anyone who wants to tackle this issue.

@steveklabnik steveklabnik added the A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools label Mar 10, 2017
@steveklabnik steveklabnik added P-medium Medium priority E-help-wanted Call for participation: Help is requested to fix this issue. E-medium Call for participation: Medium difficulty. Experience needed to fix: Intermediate. and removed A-docs labels Mar 24, 2017
@webbm
Copy link

webbm commented Mar 24, 2017

@steveklabnik, I would like to work on this.

@steveklabnik
Copy link
Member Author

@webbm awesome, please let me know if you need anything.

@mandeep
Copy link
Contributor

mandeep commented Apr 4, 2017

Hi @webbm! Before I start working on some of the items on the checklist I wanted to check with you to see which items are still available so that we don't duplicate effort.

@webbm
Copy link

webbm commented Apr 4, 2017

@mandeep, I have done a little of 1, 2, 4, and 5 is in progress. I'm going to create a Trello board to keep track of my own progress. Should I add all these as tasks and add you?

@mandeep
Copy link
Contributor

mandeep commented Apr 7, 2017

@webbm No need for Trello just yet. I'll work on item 3 this weekend and report back.

@mandeep mandeep mentioned this issue Apr 10, 2017
Merged
@rthomas
Copy link
Contributor

rthomas commented Jun 22, 2017

@steveklabnik If no one is looking at this I'll jump in for write.

@steveklabnik
Copy link
Member Author

@rthomas I'm not aware of any active work right now, that'd be great!

@rthomas rthomas mentioned this issue Jun 22, 2017
Merged
rthomas added a commit to rthomas/rust that referenced this issue Jun 22, 2017
@rthomas
Update docs for std::fmt::format rust-lang#29355.
c5d078f 
This rewords and removes the `Arguments` section from the docs for
fmt::format.

r? @steveklabnik
@rthomas
Copy link
Contributor

rthomas commented Jun 22, 2017

I have sent PRs for write format and the Debug* entries - 4, 5, 8, 9, 10, 11, 12.

@rthomas
Copy link
Contributor

rthomas commented Jun 22, 2017

Looking at the last one (Formatter) although I am struggling to see where this is actually instantiated...

Mark-Simulacrum added a commit to Mark-Simulacrum/rust that referenced this issue Jun 28, 2017
@Mark-Simulacrum
Rollup merge of rust-lang#42831 - rthomas:master, r=QuietMisdreavus
211e09c 
Update docs for fmt::write.

rust-lang#29355

I reworded it slightly to make it more clear that the function only take
two arguments - the output and the Arguments struct that can be
generated from the format_args! macro.

r? @steveklabnik
Mark-Simulacrum added a commit to Mark-Simulacrum/rust that referenced this issue Jun 28, 2017
@Mark-Simulacrum
Rollup merge of rust-lang#42832 - rthomas:doc-fmt, r=steveklabnik
a295c0b 
Update docs for std::fmt::format rust-lang#29355.

This rewords and removes the `Arguments` section from the docs for
fmt::format.

r? @steveklabnik
frewsxcv added a commit to frewsxcv/rust that referenced this issue Jun 29, 2017
@frewsxcv
Rollup merge of rust-lang#42831 - rthomas:master, r=QuietMisdreavus
b01447f 
Update docs for fmt::write.

rust-lang#29355

I reworded it slightly to make it more clear that the function only take
two arguments - the output and the Arguments struct that can be
generated from the format_args! macro.

r? @steveklabnik
frewsxcv added a commit to frewsxcv/rust that referenced this issue Jun 29, 2017
@frewsxcv
Rollup merge of rust-lang#42832 - rthomas:doc-fmt, r=steveklabnik
48303df 
Update docs for std::fmt::format rust-lang#29355.

This rewords and removes the `Arguments` section from the docs for
fmt::format.

r? @steveklabnik
arielb1 pushed a commit to arielb1/rust that referenced this issue Jun 29, 2017
Rollup merge of rust-lang#42831 - rthomas:master, r=QuietMisdreavus
8b32c51 
Update docs for fmt::write.

rust-lang#29355

I reworded it slightly to make it more clear that the function only take
two arguments - the output and the Arguments struct that can be
generated from the format_args! macro.

r? @steveklabnik
arielb1 pushed a commit to arielb1/rust that referenced this issue Jun 29, 2017
Rollup merge of rust-lang#42832 - rthomas:doc-fmt, r=steveklabnik
5682494 
Update docs for std::fmt::format rust-lang#29355.

This rewords and removes the `Arguments` section from the docs for
fmt::format.

r? @steveklabnik
rthomas added a commit to rthomas/rust that referenced this issue Jul 2, 2017
@rthomas
Add docs for Debug* structs. rust-lang#29355
d1316b4 
This adds docs for the Debug* structs as well as examples from the
Formatter::debug_* methods, so that a user knows how to construct them.

I added these examples as the builders module is not public and hence
the debug_*_new() functions are not available to a user.

r? @steveklabnik

Review comments.

Mainly adding in the links for all of the structs and functions.

Remove rust tag on code blocks.
Mark-Simulacrum added a commit to Mark-Simulacrum/rust that referenced this issue Jul 4, 2017
@Mark-Simulacrum
Rollup merge of rust-lang#42836 - rthomas:29355-debug, r=GuillaumeGomez
93e46a9 
Update docs for Debug* structs. rust-lang#29355

This adds docs for the Debug* structs as well as examples from the
Formatter::debug_* methods, so that a user knows how to construct them.

I added these examples as the builders module is not public and hence
the debug_*_new() functions are not available to a user.

r? @steveklabnik
rthomas added a commit to rthomas/rust that referenced this issue Jul 13, 2017
@rthomas
Update docs on Error struct. rust-lang#29355
aca6cd0 
This adds a pretty contrived example of the usage of fmt::Error. I am
very open to suggestions for a better one.

I have also highlighted the fmt::Error vs std::error::Error.

r? @steveklabnik
Mark-Simulacrum added a commit to Mark-Simulacrum/rust that referenced this issue Jul 18, 2017
@Mark-Simulacrum
Rollup merge of rust-lang#42837 - rthomas:29355-error, r=steveklabnik
b83285b 
Update docs on Error struct. rust-lang#29355

This adds a pretty contrived example of the usage of fmt::Error. I am
very open to suggestions for a better one.

I have also highlighted the fmt::Error vs std::error::Error.

r? @steveklabnik
@Mark-Simulacrum Mark-Simulacrum added the C-tracking-issue Category: An issue tracking the progress of sth. like the implementation of an RFC label Jul 24, 2017
@brennie brennie mentioned this issue Oct 5, 2017
Merged
kennytm added a commit to kennytm/rust that referenced this issue Oct 8, 2017
@kennytm
Rollup merge of rust-lang#45042 - brennie:brennie/fmt-trait-summaries…
4090e81 
…, r=steveklabnik

Update trait summaries for std::fmt

This patch is part of rust-lang#29355.

r? @steveklabnik
@71 71 mentioned this issue Dec 8, 2017
Closed
@mahdi-shojaee
Copy link

  • Formatter should show where it's created, and talk about the details more.

+1

@steveklabnik
Copy link
Member Author

I'm going to send in a PR to help Formatter; after that, all of this is done enough. The module docs are still very huge, but I don't have concrete suggestions at this time. Thank you everyone!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools C-tracking-issue Category: An issue tracking the progress of sth. like the implementation of an RFC E-help-wanted Call for participation: Help is requested to fix this issue. E-medium Call for participation: Medium difficulty. Experience needed to fix: Intermediate. E-mentor Call for participation: This issue has a mentor. Use #t-compiler/help on Zulip for discussion. P-medium Medium priority
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
6 participants
@steveklabnik @rthomas @webbm @mahdi-shojaee @Mark-Simulacrum @mandeep