Repository navigation
Aliki: Hard to discern method blocks visually #1573
Description
I find it really hard to see where a method documentation starts and ends:
The headers "Args" and "Description" are much bigger than the method name although they are subordinate to it. This means when scrolling through the page it is hard - at least for me - to discern the part that belongs to a method.
I'm not sure whether this is the same problem but the right side bar is also quite useless in this case:
It is just a list of "Args" and "Description" entries without a hint for what.
Activity
st0012 commentedon Jan 19, 2026
Both
ArgsandUsageheaders are specific to this particular documentation's style. It's not something the theme inserts.Currently RDoc doesn't enforce much format for individual method's documentation, and usually headers are avoided due to the same confusing effect you reported. But I also don't plan to limit the elements users can use based on the location (e.g. prohibit headers in method blocks).
If you ask me, the
Argscan simply be a list. AndDescriptionis simply redundant.gettalong commentedon Jan 20, 2026
@st0012 I get that you don't want to restrict the usage of elements. However, this is not just a visual problem but also a semantic problem.
Each HTML page should have exactly one h1 heading, in the case of https://docs.ruby-lang.org/en/4.0/URI/RFC2396_Parser.html this would be
class URI::RFC2396_Parserat the top.Then each further heading level should be correctly structured but isn't here. You can already see this in the right sidebar (or the second image). For example, the heading "Public instance methods" uses an h3 header and is shown underneath "Example" which is an h2 but this ordering is wrong.
So semantically speaking the individual section headers "Attributes", "Public instance methods" and so on should be h2 and any documentation underneath should start with h3 headings.
The right sidebar menu is automatically generated via Javascript from the headings. So it might also be useful to make the method names into headers so that they appear in the sidebar and we have an integrated quick jump menu.