Add TreeSet example #15668
Add TreeSet example #15668
Conversation
| //! for i in tree_set.iter() { | ||
| //! println!("{}", i) | ||
| //! } | ||
| //!``` |
There was a problem hiding this comment.
Perhaps this should go on the TreeSet struct definition instead?
You may also want to mix up the order of inserts and then comment saying that it prints 1 2 3
There was a problem hiding this comment.
That's true. It's nice to have a very simple example as the module definition, what do you think about both places?
And yeah, mixing it up sounds good.
There was a problem hiding this comment.
We haven't really figured out the best way to do this yet, for example the hashmap type has a small module description but a large type description.
On the other hand, the result module has a large description while the type has a small description.
I suppose as long as it's somewhere it's ok. I think for collections they're susceptible to being reexported a good bit, so maybe reexported things favor the type while other things (like result) are up in the air?
There was a problem hiding this comment.
Hmmm, that might be a decent heuristic.
One thing that comes up is http://doc.rust-lang.org/std/collections/hashmap/index.html comes up before http://doc.rust-lang.org/std/collections/hashmap/struct.HashMap.html when you search for 'hashmap', which I've always found a bit irritating. I think I prefer having at least some kind of reasonable overview on the module. Ideally each of these pages lives mostly on its own, with the module having overview and the type having just details.
|
I've made the operations out of order, and added the definition to both. Eventually, I'll write more for the module reference. |
| @@ -12,6 +12,19 @@ | |||
| //! trees. The only requirement for the types is that the key implements | |||
| //! `Ord`. | |||
|
|
|||
| //! ## Example | |||
There was a problem hiding this comment.
Does this render correctly? (I'm not sure if markdown handles a paragraph directly running into a heading, since there's no //! on the previous line.)
There was a problem hiding this comment.
I could not get friggin' rustdoc to generate any documentation on this file, complaining about glob imports and such. I also tried to run it on src/libcollections/lib.rs, and same deal.
There was a problem hiding this comment.
Well, you'll definitely have to run it on the whole crate rather than just this module, not sure about the other error.
Maybe make doc/collections/index.html NO_REBUILD=1? (I'm not 100% sure if NO_REBUILD works with that target.)
There was a problem hiding this comment.
On that note, these examples will need the appropriate imports (I guess just TreeSet).
There was a problem hiding this comment.
Ugh, I thought that lib.rs was the crate. Lemme check this.
There was a problem hiding this comment.
What were the errors you ran into when running rustdoc src/libcollections/lib.rs? Also, if you want to run the tests, you can just run rustdoc --test src/libcollections/lib.rs
There was a problem hiding this comment.
(Oh, yeah, I just meant running on treemap.rs in isolation wasn't going to work... your other lib.rs invocation is the only one that has a reasonable hope of succeeding.)
There was a problem hiding this comment.
So, now, of course, running rustdoc on lib.rs does work. I have re-compiled rustc between then and now, and I basically assumed that was probably the problem.
This does not render correctly, but adding a //! in doesn't seem to fix it either.
There was a problem hiding this comment.
Maybe you need a blank line (i.e. //!) before and after? I'm not sure.
There was a problem hiding this comment.
Whoops:
@@ -11,8 +11,9 @@
//! An ordered map and set implemented as self-balancing binary search
//! trees. The only requirement for the types is that the key implements
//! `Ord`.
-
+//!
//! ## Example
+//!
//! ```{rust}
//! let mut tree_set = TreeSet::new();
//!
@@ -23,7 +24,7 @@
//! for i in tree_set.iter() {
//! println!("{}", i) // prints 1, then 2, then 3
//! }
-//!```
+//! ```
Pushing fix now.
|
@alexcrichton since I force pushed, your retry isn't gonna work, I bet. Unless bors is super smart? |
|
I think these will still need to import |
|
of course! Ignore the fact that I had to force push one more time to add that because I forgot the --test on Thank $DIETY for @bors, that's all I have to say. |
|
Ugh, don't know how that whitespace got in there. @alexcrichton , it is now fixed. |
|
Good to go again. |
…hton Someone asked for an example usage of this on IRC, so I tossed together the simplest one. Obviously, this isn't up to snuff, but it's better than nothing.
…ykril feat: add backtick to surrounding and auto-closing pairs Makes backticks always complete as a pair and also surround the current selection, similar to double quotes. This is useful primarily in the context of markdown doc comments, but is applied globally for simplicity. Closes rust-lang/rust-analyzer#11381
Someone asked for an example usage of this on IRC, so I tossed together the simplest one. Obviously, this isn't up to snuff, but it's better than nothing.