POC of a new design for the generated rustdoc

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

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

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.

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

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).

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

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

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

1 Like

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.

3 Likes

I can strongly vouch for:

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

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.

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?

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.

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

Woah I love that new sidebar!

I'm not keen on many elements of this, but to name just one, the pages for each function seem to not show the function signature

The missing function signature is one of many bugs. Currently it just modify the DOM of the actual documentation on the fly, some pieces are lost in the operation and the function signature is one of them.

I will not spend a lot of time to fix bugs since this is just a POC to get a general idea of what the new design may look like, not something for everyday use. If I decide to make this official I will do this from scratch using the rustdoc tool.

But I am interested by your other complains, especially if it's about the intended behavior.

I like it! I need to invest further on what should improved or what needs improvement but that's definitely nice.

2 Likes

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.