POC of a new design for the generated rustdoc

documentation
#2

I do like the very-compact list of things with --oneline descriptions.

I'm not certain that alphabetical is the best option for it. Having ne and eq not be next to each other is unfortunate. That said, I don't have a concrete suggestion for you here.

nit: There's something strange going on with the "Home" key on your prototype -- it usually goes back to the top, which I used to try to get back to the list, but it didn't work, behaving more like

2 Likes
#3

What about sorting by the second column and then the first to get ne and eq next to each other?

#4

I believe alphabetical order is more convenient to find quickly what you are looking for since you usually have an idea of the name of the method while the traits have no special order.

It might be possible to add an option to switch from grouping by name, to grouping by trait.

#5

Thank you for working on this! I agree with you that there is room for improvement on rustdoc. I'm not convinced this exact design nails it though.

Things I like:

  • compactness
  • a search bar always visible. Even though with rustdoc it's only an "s" hotkey away, I have a hard time adapting to it and often have the reflex of scrolling. However I think it should be an instant "as you type" filter on the outline.
  • I do prefer an outline on the left above the sections "Modules", "Macros", "Structs", "Traits", etc of rustdoc, which don't have much informational value. However I think there is a problem in practice. Many rust libraries are organized in modules for the developer convenience, but those modules are private, and items are re-exported. That somewhat beats the point of an outline if it becomes a mostly flat list under "prelude". That being said maybe we need to see it on some crates to get a feel for it, because I think it's still nicer to see that list at the left than to have to go all the way to the bottom of a long readme to find it. In any case on the standard library a foldable outline is top! I feel like I "see" the standard library for the first time! It makes me want to browse it to discover it. Rustdoc never did that for me, thanks!
  • Inclusion of the book. It would need a good UI design, but I can totally see it being integrated in the api docs (I mean even the other books, reference, nomicon, rust by example, ...) Eg a really integrated total documentation of rust in one interface. There could be links between the api docs and guide level documentation for more examples, explanation, ... It would also be nice if crates could easily include a user guide straight in the api docs.

Things I don't like:

  • Rust being a type strict language I really want to see the declaration of the type. I think it's nice of rustdoc to show that all the way at the top. It's what I look at most.
  • Look and feel. A lot of work there, but that's ok for POC. I do like the look and feel of rustdoc + ayu-dark.
  • fluidity. On my wide screen there is a whole empty area on the right. Ideally there is a well thought out design for every level, from a phone to a 4k screen that really makes good use of all the available screen space.

Mitigated:

  • I like alphabetic sorting, but I think I would like at least a button that let's you order and group by implemented traits.
  • Not quite sure of the usefulness of the long methods tab. I think I would be more in favor of clicking in the item list folds open a section for the item, pushing escape closes it again. Btw I would do thing like links to the books in a similar way, overlay, so you can read and browse, escape it hides again and you are still in the api docs where you left of.

Ok, there is surely a lot more to say, but I'll leave that to others.

5 Likes
#6

I like the compact table at the top with all the methods and their 1-line descriptions. It gives a good overview of what the type can do. It'd be great for Option or Vec which have lots of convenience methods.

The sidebar with filesystem-like navigation seems useful too. In the current rustdoc it's confusing, because it's sometimes navigation between sibling pages, sometimes navigation within the same page, and the structure is not clear.

6 Likes
#7

Above that, I'd love to see "Trait implementations" section completely reimagined (in general, since both rustdoc and this concept show it in the same way).

The trait section shows so much detail that it misses the forest for the trees. It may display 20 versions of impl<something> Extend<something> for Type<something>, each time with duplicate description of the fn extend, but what it's really trying to say is that the type has an .extend() method that works with several types of parameters.

And there are special traits Ord/Eq/Add/Sub/Mul/Shr which are not important for their own methods, but for what they enable for their type. So maybe they should be handled differently, with a note such as "This type can be compared and used with the following arithmetic operators…".

Similarly with IntoIterator, instead of displaying the trait description, which is more of an implementation detail, it could be replaced with a more concise note along the lines of "This is a container which can be iterated".

6 Likes
#8

It sure could have 20 lines of impl<something> Extend<something> for Type<something> followed by just once the method, if the method didn't have any impl specific docs.

#9

I love to see different approaches. I also like the compact list of methods!

I think that, at the very least, inherent methods and trait methods should be separated. I would prefer if methods were in source order, so that the crate author can design the docs for maximum readability — for a HashMap we expect the basic methods like new, len and get to be near the top.

If the crate author can't determine the order exactly, maybe it would be possible to assign methods to groups and determine the group order?

Having .borrow() as the first method gives it undue attention. This is ultimately confusing for readers, and they will think it's an important method. (The Borrow trait has a blanket impl, so every type will have this method, and I've never used it on a HashMap value!).

6 Likes
#10

I did some changes on the POC according to the feedback.

You are right. I wanted to use a list with icons for consistency, but to display information about generics or enum variants, showing directly the declaration is better. I fixed that.

Yes I did not implemented l&f and responsive design since it's just a POC. They are a lot ok things that can be adjusted. My main concern was not the look but the ways to navigate through the doc.

You are right. Grouping by implementation might me better to have an overview, while grouping by method might be better when you have an idea of what you are looking for. I added a button to switch from a method focused view to an implementation focused view.

I'm not sure a lot of people sort the methods in the source by order of importance for the user. And methods from traits might be as useful as inherent methods(even if it is true that blanket and Auto implementations are often less important).

#12

Given that this is the behavior of the existing rustdoc, and that the standard library provides such nicely ordered methods, I would on the contrary expect that many people are conscientious of this (and those who aren't ought to be!).

(Granted, there is the question of how rustdoc handles inherent impls in other modules. I can only hope they are grouped by module, with those from the struct's own module guaranteed to be first).

I will concede this is true for some crates like rand (and the current form of rustdoc often makes this worse by collapsing these methods from view). I still don't think an alphabetical listing of all methods is superior.

On a related note, I think alphabetical sorting across all traits could actually cause confusion when an inherent method shadows a trait method. See RefCell::borrow, or virtually all inherent methods of frunk::HCons.

1 Like
#13

I had no idea there was a search hotkey in the existing docs, so I think that goes a long way toward showing the better discoverability of an omnipresent search bar.

2 Likes
#14

At least on my comp, it literally says "Click 'S' to search, '?' for more options..." in the search bar.

1 Like
#15

I had to go check and, sure enough, it’s there... in a washed out light grey on white in an area that just looks like text, not a search box.

image
0570346E-1ADD-4043-9026-0852B887A08D.png1334×750 76.1 KB

3 Likes
#16

I can strongly vouch for:

#17

Thank you for sharing this PoC!

I really like the outline the global crate outline, I think it would really help when browsing a crate's documentation.

On the other hand, I'm not a fan of the "alphabetically sorted long list of methods". Or rather, I do think it is useful to have it somewhere, to have the basic information of "what can I call on my type", but maybe not as the first contact with a type. Also I think it could get ugly in certain situations (e.g. a type that implements Iterator and get all of the Iterator methods... to me this would add a lot of noise to the method list).

I don't have a PoC for this, but I would really like rustdoc to be more "capabilities oriented". By this I mean that it should present more "semantic" information about what a user can do with a type. For example:

Construction

  • Contains Self { field : Type, field : Type } if it is available
  • Lists all methods that return Self, Option<Self> or Result<Self>
  • Indicates if the type implements Clone

Conversion

  • Lists all types for which this type implements From (could also go in "Construction" section)
  • Lists all types for which this type implements Into

Iterator

  • If the type is an iterator, indicate the item type.
  • Also special-cased for DoubleEndedIterator and ExactSizeIterator

Future

  • If the type is a future, indicate the item type.

Operations

  • Indicates if the type is Hash
  • Lists all types to which this type is Comparable (Eq, PartialEq or Ord, PartialOrd)
  • Lists all types with which this type has arithmetic operations implemented. For each such type, indicate the available operations.

Formatting

  • Indicates if the type is Debug or Display

Ideally, instead of special-casing everything, traits could add indications to rustdoc in their documentation of how they should appear in the documentation of implementors. This would allow for instance pyo3 PyInto to appear under the "Conversion" section, or serde's Serializable to appear as a small colored tag next to the type name.

8 Likes
#18

The pages don't render well on mobile. It would be better if the side bar hid itself, and the description was moved down to the line below to accommodate the smaller screen size.

#19

Those items sound like great additions. Do you imagine the "Lists all types for ..." to be on the same page and being extended? I mean this could add to the overall size and being more distrustful distractful or do you imagine to have a separate section where i can extend those if i need them?

#20

Well, I'm not a web developer, so I wouldn't know the various technical options we have and their impact on performance in various scenarios (like a type which has a lot of conversions. For the "all the types such..." I was thinking to a list containing just the names of the various types, maybe as colored buttons (pretty much like SO renders tags or this forum renders the categories of a post), but I'm not much of a designer either, so I guess I would have to experiment and see if I can get something good out of the ideas. I'll see if I can find the time someday.

#21

POC : take two

I updated the POC according to the feedback from this thread and my own experience using it.

This time it is not limited to a few handmade pages. The html page of the new poc load the current documentation pages via the fetch API and converted them on the fly to the new format through DOM manipulation. It is a terrible hack, but you can now browse most of the documentation.

A few changes:

  • added a recap of all the implementations
  • moved back the description as first
  • added the ability to group either by implementation(unsorted by default) or by method name(sorted by default)
  • added the ability to sort or not (not sure I will keep it since the default seems fine to me)

What does not work yet but should be fixed :

  • traits pages
  • book pages

What probably won't be fixed because not the target of this POC :

  • Reactive design (View on smartphone)
  • the visuals : icons, fonts, code blocs, ...
  • cross-page links (most are broken but the sidebar should work)
  • back button (broken)

While I like a lot the zkr idea. It raise a lot of questions, so I will consider it maybe in another version of the POC

https://utherii.github.io/new.html

7 Likes
#22

Woah I love that new sidebar!