rust-lang/rust

API Docs: fmt

Closed this issue · 12 comments

steveklabnik commented

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 commented

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

webbm commented

@steveklabnik, I would like to work on this.

steveklabnik commented

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

  • 👍1
mandeep commented

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 commented

@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 commented

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

rthomas commented

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

steveklabnik commented

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

rthomas commented

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

rthomas commented

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

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

+1

steveklabnik commented

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!

  • 👍1