Update docs for Debug* structs. #29355 #42836

rthomas · 2017-06-22T19:53:03Z

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

rust-highfive · 2017-06-22T19:53:11Z

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @steveklabnik (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

GuillaumeGomez · 2017-06-27T21:34:55Z

src/libcore/fmt/builders.rs

@@ -51,7 +51,33 @@ impl<'a, 'b: 'a> fmt::Write for PadAdapter<'a, 'b> {

 /// A struct to help with `fmt::Debug` implementations.
 ///
-/// Constructed by the `Formatter::debug_struct` method.
+/// This is useful when you wish to output a formatted struct as a part of your
+/// `Debug::fmt` implementation.


Missing the url to the corresponding struct.

GuillaumeGomez · 2017-06-27T21:35:03Z

src/libcore/fmt/builders.rs

+/// This is useful when you wish to output a formatted struct as a part of your
+/// `Debug::fmt` implementation.
+///
+/// This can be constructed by the `Formatter::debug_struct` method.


Missing the url to the corresponding struct.

GuillaumeGomez · 2017-06-27T21:35:32Z

src/libcore/fmt/builders.rs

+/// impl fmt::Debug for Foo {
+///     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
+///         fmt.debug_struct("Foo")
+///             .field("bar", &self.bar)


Indent is a bit off: should be aligned to ".debug_struct".

GuillaumeGomez · 2017-06-27T21:35:48Z

src/libcore/fmt/builders.rs

@@ -118,7 +144,30 @@ impl<'a, 'b: 'a> DebugStruct<'a, 'b> {

 /// A struct to help with `fmt::Debug` implementations.
 ///
-/// Constructed by the `Formatter::debug_tuple` method.
+/// This is useful when you wish to output a formatted tuple as a part of your
+/// `Debug::fmt` implementation.


Missing the url to the corresponding struct.

GuillaumeGomez · 2017-06-27T21:35:55Z

src/libcore/fmt/builders.rs

+/// This is useful when you wish to output a formatted tuple as a part of your
+/// `Debug::fmt` implementation.
+///
+/// This can be constructed by the `Formatter::debug_tuple` method.


Missing the url to the corresponding method.

GuillaumeGomez · 2017-06-27T21:36:07Z

src/libcore/fmt/builders.rs

@@ -230,7 +279,27 @@ impl<'a, 'b: 'a> DebugInner<'a, 'b> {

 /// A struct to help with `fmt::Debug` implementations.
 ///
-/// Constructed by the `Formatter::debug_set` method.
+/// This is useful when you wish to output a formatted set of items as a part
+/// of your `Debug::fmt` implementation.


Missing the url to the corresponding struct.

GuillaumeGomez · 2017-06-27T21:36:13Z

src/libcore/fmt/builders.rs

+/// This is useful when you wish to output a formatted set of items as a part
+/// of your `Debug::fmt` implementation.
+///
+/// This can be constructed by the `Formatter::debug_set` method.


Missing the url to the corresponding method.

GuillaumeGomez · 2017-06-27T21:36:25Z

src/libcore/fmt/builders.rs

@@ -279,7 +348,27 @@ impl<'a, 'b: 'a> DebugSet<'a, 'b> {

 /// A struct to help with `fmt::Debug` implementations.
 ///
-/// Constructed by the `Formatter::debug_list` method.
+/// This is useful when you wish to output a formatted list of items as a part
+/// of your `Debug::fmt` implementation.


Missing the url to the corresponding struct.

GuillaumeGomez · 2017-06-27T21:36:32Z

src/libcore/fmt/builders.rs

+/// This is useful when you wish to output a formatted list of items as a part
+/// of your `Debug::fmt` implementation.
+///
+/// This can be constructed by the `Formatter::debug_list` method.


Missing the url to the corresponding method.

GuillaumeGomez · 2017-06-27T21:36:37Z

src/libcore/fmt/builders.rs

@@ -328,7 +417,27 @@ impl<'a, 'b: 'a> DebugList<'a, 'b> {

 /// A struct to help with `fmt::Debug` implementations.
 ///
-/// Constructed by the `Formatter::debug_map` method.
+/// This is useful when you wish to output a formatted map as a part of your
+/// `Debug::fmt` implementation.


Missing the url to the corresponding struct.

GuillaumeGomez · 2017-06-27T21:36:42Z

src/libcore/fmt/builders.rs

+/// This is useful when you wish to output a formatted map as a part of your
+/// `Debug::fmt` implementation.
+///
+/// This can be constructed by the `Formatter::debug_map` method.


Missing the url to the corresponding method.

rthomas · 2017-07-01T17:30:52Z

Thanks, I've addressed all of the comments.

GuillaumeGomez

Just one last nit and it should be good!

GuillaumeGomez · 2017-07-02T16:13:53Z

src/libcore/fmt/builders.rs

+///
+/// # Example
+///
+/// ```rust


No need to add rust tag. By default, every code block is a rust one.

GuillaumeGomez · 2017-07-02T16:14:17Z

src/libcore/fmt/builders.rs

-/// Constructed by the `Formatter::debug_tuple` method.
+/// # Example
+///
+/// ```rust


GuillaumeGomez · 2017-07-02T16:14:24Z

src/libcore/fmt/builders.rs

 ///
-/// Constructed by the `Formatter::debug_set` method.
+/// ```rust


GuillaumeGomez · 2017-07-02T16:14:31Z

src/libcore/fmt/builders.rs

+///
+/// # Example
+///
+/// ```rust


GuillaumeGomez · 2017-07-02T16:14:39Z

src/libcore/fmt/builders.rs

+///
+/// # Example
+///
+/// ```rust


GuillaumeGomez · 2017-07-02T16:15:32Z

Also, once updated, can you squash your commits to only have one please?

@steveklabnik

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.

rthomas · 2017-07-02T16:43:31Z

Fixed the rust tags on code blocks and squashed the commits.

GuillaumeGomez · 2017-07-03T09:32:25Z

Thanks!

@bors: r+ rollup

bors · 2017-07-03T09:32:25Z

📌 Commit d1316b4 has been approved by GuillaumeGomez

bors · 2017-07-03T09:32:37Z

⌛ Testing commit d1316b4 with merge c354c68cf5254236dfdb68b791b44110f691dc53...

bors · 2017-07-03T10:36:07Z

💔 Test failed - status-travis

rthomas · 2017-07-03T12:10:08Z

I'm unsure why this docs change is failing, could the test be flakey?

This is from the build logs:

[00:59:34] command did not execute successfully: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0/bin/cargo" "test" "-j" "4" "--target" "x86_64-unknown-linux-musl" "--release" "--locked" "--color" "always" "--manifest-path" "/checkout/src/libstd/Cargo.toml" "--features" "panic-unwind jemalloc backtrace" "-p" "std:0.0.0" "-p" "rustc_lsan:0.0.0" "-p" "std_unicode:0.0.0" "-p" "collections:0.0.0" "-p" "unwind:0.0.0" "-p" "alloc:0.0.0" "-p" "rustc_tsan:0.0.0" "-p" "compiler_builtins:0.0.0" "-p" "libc:0.0.0" "-p" "panic_abort:0.0.0" "-p" "rand:0.0.0" "-p" "core:0.0.0" "-p" "rustc_msan:0.0.0" "-p" "rustc_asan:0.0.0" "-p" "alloc_system:0.0.0" "--"
[00:59:34] expected success, got: exit code: 101
[00:59:34] 
[00:59:34] 
[00:59:34] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap test --target x86_64-unknown-linux-musl
[00:59:34] Build completed unsuccessfully in 0:58:11

GuillaumeGomez · 2017-07-03T13:10:21Z

Hum, strange...

alexcrichton · 2017-07-03T17:30:04Z

@bors: retry

@steveklabnik

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

Rollup of 8 pull requests - Successful merges: #42227, #42836, #42975, #42994, #43041, #43042, #43043, #43045 - Failed merges:

rust-highfive assigned steveklabnik Jun 22, 2017

rthomas changed the title ~~Add docs for Debug* structs. #29355~~ Update docs for Debug* structs. #29355 Jun 22, 2017

shepmaster added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jun 23, 2017

GuillaumeGomez reviewed Jun 27, 2017

View reviewed changes

arielb1 added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jun 27, 2017

GuillaumeGomez reviewed Jun 27, 2017

View reviewed changes

GuillaumeGomez requested changes Jul 2, 2017

View reviewed changes

rthomas force-pushed the 29355-debug branch from fd30241 to d1316b4 Compare July 2, 2017 16:42

GuillaumeGomez approved these changes Jul 3, 2017

View reviewed changes

Mark-Simulacrum mentioned this pull request Jul 4, 2017

Rollup of 8 pull requests #43051

Merged

bors added a commit that referenced this pull request Jul 4, 2017

Auto merge of #43051 - Mark-Simulacrum:rollup, r=Mark-Simulacrum

2fbba5b

Rollup of 8 pull requests - Successful merges: #42227, #42836, #42975, #42994, #43041, #43042, #43043, #43045 - Failed merges:

bors merged commit d1316b4 into rust-lang:master Jul 4, 2017

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update docs for Debug* structs. #29355 #42836

Update docs for Debug* structs. #29355 #42836

rthomas commented Jun 22, 2017

rust-highfive commented Jun 22, 2017

GuillaumeGomez Jun 27, 2017

GuillaumeGomez Jun 27, 2017

GuillaumeGomez Jun 27, 2017

GuillaumeGomez Jun 27, 2017

GuillaumeGomez Jun 27, 2017

GuillaumeGomez Jun 27, 2017

GuillaumeGomez Jun 27, 2017

GuillaumeGomez Jun 27, 2017

GuillaumeGomez Jun 27, 2017

GuillaumeGomez Jun 27, 2017

GuillaumeGomez Jun 27, 2017

rthomas commented Jul 1, 2017

GuillaumeGomez left a comment

GuillaumeGomez Jul 2, 2017

GuillaumeGomez Jul 2, 2017

GuillaumeGomez Jul 2, 2017

GuillaumeGomez Jul 2, 2017

GuillaumeGomez Jul 2, 2017

GuillaumeGomez commented Jul 2, 2017

rthomas commented Jul 2, 2017

GuillaumeGomez commented Jul 3, 2017

bors commented Jul 3, 2017

bors commented Jul 3, 2017

bors commented Jul 3, 2017

rthomas commented Jul 3, 2017 •

edited

Loading

GuillaumeGomez commented Jul 3, 2017

alexcrichton commented Jul 3, 2017

Update docs for Debug* structs. #29355 #42836

Update docs for Debug* structs. #29355 #42836

Conversation

rthomas commented Jun 22, 2017

rust-highfive commented Jun 22, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rthomas commented Jul 1, 2017

GuillaumeGomez left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

GuillaumeGomez commented Jul 2, 2017

rthomas commented Jul 2, 2017

GuillaumeGomez commented Jul 3, 2017

bors commented Jul 3, 2017

bors commented Jul 3, 2017

bors commented Jul 3, 2017

rthomas commented Jul 3, 2017 • edited Loading

GuillaumeGomez commented Jul 3, 2017

alexcrichton commented Jul 3, 2017

rthomas commented Jul 3, 2017 •

edited

Loading