JavaDoc skin?

language design
1

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

2

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
3

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
4

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

5

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