Documenting a struct with a large number of methods

1

I have been working on my implementation of a version of std::Vec, including unstable methods, which has a large number of methods ( I think nearly 80 ). I have a distant memory of being a little confused when I first learned Rust by the very long list of Vec methods, so I thought I would try and organise them somewhat make it easier to comprehend them. So I have settled on 4 implementation sections: Construct Basic Allocation Conversions.

What do you think about this? I think something similar would be an improvement to std::Vec.

6 Likes
2

Yeah, this is a good direction. It would be great to have a dedicated rustdoc feature for this to make these sections rendered more clearly, and visible in the sidebar.

4 Likes
3

I think the best version of this is something like https://doc.rust-lang.org/std/option/index.html#method-overview does instead.

Otherwise you run into limits of hierarchies problems. Like is https://docs.rs/pstd/latest/pstd/vec/struct.Vec.html#method.from_fn a conversion method or an allocation method or a creation method, for example?

Plus the method details tend to make it somewhat large no matter how organized -- especially when methods have sufficient examples -- so separate tables that can be compact are nice.

3 Likes
4

Yes, that is nice, and must have taken a lot of work, but I was thinking more about “minimal” auto-generated Impl documentation, with relatively little work other than putting the methods into a sensible order within sensible Impl sections. I am still thinking about the details of the hierachy, but with so many methods, I think some kind of grouping helps.

I guess I partly wanted to point out the current Implementations section of std::Vec, in terms of grouping related methods together, seems to me to be a bit of a confusing mess! Also, you cannot even get to where it starts without a lot of scrolling, or perhaps by guessing a method that appears early on.

1 Like
5

Yes, it’s a good idea. It’s sad the titles don’t appear on the left panel; maybe a suggestion for Cargo doc? But the summary at the top helps a lot.

I did something similar to what @scottmcm has shown. It works well to introduce the crate or any time explanations to support the search are helpful, though it requires much more work to write and to maintain. But for a quick reference search, having the titles on the left would be helpful, too.

6

Depending on what you want to achieve with this implementation, you can also group methods into traits and implement them for your vec. This of course is not an option if your goal is to provide a drop-in replacement for alloc::vec::Vec.

7

Remember that lots of code in the standard library is ancient. It's probably just sticking things into whatever impl block had the right trait requirements at the time, and not really thinking about it.

Though there's an interesting thing to consider there: it's possible to always put bounds on the methods instead of the impl block. I don't know whether that's better, but it does allow putting the T: Copy and T: Clone versions of things next to each other, which tends not to happen if one prefers impl-level bounds. (Or you could put the T: Copy one in the T: Clone block, with the extra where T: Copy on the method.)

Dunno how people feel about that overall, though.

8

Yes, I think that is a better way to do it, although it doesn’t entirely account for what I am calling a mess. One thing I found impossible is to put plain Vec::new in an impl<T, A: Allocator> Vec<T, A> impl. If I try the errors are very strange…. So I have an impl<T> Vec<T> for just that, which is the Construct section. I now have six section: Construct Basic Advanced Allocation Conversion Non-Panic.

9

Well Vec::new() shouldn't be allocating, so that makes sense to me.

1 Like
10

Well I do have

pub fn with_capacity(capacity: usize) -> Vec<T> {
let mut v = Vec::<T>::new();
v.set_capacity(capacity).unwrap();
v
}

in an impl<T, A: Allocator> Vec<T, A> impl, which works ok ( edit: oh, now I test it, it doesn’t! )

There is some deep mystery there ( or even a compiler bug maybe ) which I don’t understand.

Edit: well I am starting to understand, it will compile, but when you try to call it it complains about type inferring the result. Which I don’t really understand yet, but I know what works and what doesn’t!

11

You forgot the code block fencing, and it's removing a bunch of what you wrote.

1 Like
12

That page is fantastic! But I never saw it before, because it's not the Option type's page. All the links and search results go to the type, not the module.

It's good content, but it's not where rustdoc draws all the attention to. So the problem of the type's own page being sub-par and not well organised remains. You can add "no, don't read this page, go to the nice one" in docs for all the methods, but that's a band aid.

1 Like