JavaDoc skin?

Once I read that you can customize RustDoc themes. The boring thing is that it's currently possible only locally or if you upload the built docs out of www.docs.rs.

But did you ever consider Oracle API skin? I like the current RustDoc style, but I also find the Oracle style interesting. Maybe RustDoc could try adding a similiar skin?

Here's another JavaDoc example: https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/lang/Byte.html

Rustdoc themes are CSS only. I'm not sure you can emulate Oracle's API style using only CSS and no HTML changes.

2 Likes

I do miss the javadoc summary tables, they're a feature that rustdoc is sorely lacking. I don't think this can really be emulated with CSS, maybe approximated a bit.

Javadoc Summary tables:

  • responsive layout - from portrait smartphone to fullscreen landscape desktop
  • mostly one line per item / consistent vertical space consumption
  • arguments and return types are separated, making it easy to scan for a matching signature
  • displays the first line of the doc comment

Rustdoc collapsed mode:

  • only designed for narrow displays
  • horizontally jagged (no alignment)
  • vertically jagged (where clauses)
  • sometimes witches argument layout from horizontal to vertical
  • need to click to get even the summary

Both are bad when it comes to displaying trait/supertype methods. In javadoc it's just a bunch of lists without details, in rustdoc the methods are there but it's even less readable than the collapsed inherent method list because one has to first expand everything to see trait methods.

2 Likes

Can the Rust team consider this? Can you change the looks of RustDoc output and reflect that on docs.rs? Even if you don't want it to look like Java, maybe can't you change the looks of it to look a bit more beautiful?

Look at my case: File in rialight_filesystem - Rust It looks so cryptic...