The first format looks better and makes more sense.
3 Likes
Given that there's only one subtitle per page, would it actually be beneficial to bold it?
I mean, it's always the first line on the page, and I'd believe bolding things which don't really need the emphasis just makes clutter.
I think you're right that it doesn't exactly fit in, but I don't think bolding it will improve that - it'll just make it stick out more, and it'll still be kind of ugly.
I actually agree a lot with the idea (maybe slightly less bolded). Indeed the first line of a doc comment is special: it's the only line that appears when "previewing" the description of an item, which may be something easy to miss when one is on the main item's documentation.
Example
That is, it is an error to have a docstring of the form:
/// This type serves several purposes:
///
/// - Fooing
///
/// - Baring
which is not something obvious when one looks at:
Indeed, when looking at the "preview", we get this "unterminated" / truncated description:
If we had, on the main page documentation, a way to highlight the very same line that is displayed alone on previews, then this kind of "mistakes" would be easier to spot:
Another approach to this issue would be a #[doc(short = "A multi-purpose type")] attribute, to customize the documentation that appears when "previewing" an item.
And if short were named title or subtitle, with the associated docstring then showcased even on the main item, then we are back to the question at hand, but having replaced a positional docstring with a keyword-designated one.
2 Likes
Mainly I don't think subtitles should be written like sentences. Subtitles are sentence fragments. But a better place to start might be the front page of rust-lang.org
If anything, on this page, the short description is entirely redundant with the following introduction paragraph, and ideally would be edited out.
Or perhaps, given the intended target of the first one-sentence description as a quick overview from the higher page:
it might make more sense to display it with the title line as a proper subtitle (this is just bad html-hacking to show the concept):
The formal style of API docs like this is really not clear, though. The best we can really do here is look at how different doc tools handle this, and I think rustdoc's output is one of the most usable and friendly doc pages that I've seen in any language.
1 Like
This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.