Custom order of sections (tags)

[athityakumar]

Currently, by default, YARD Doc has this order of sections : description, @examples, @params, @return. But I'd like to have an order like description, @params, @return and then @examples.

Is there any way of doing with some yardopts config? I'm afraid that a custom templating will not work, as this is hosted on rubydoc.info

[lsegal]

There is currently no easy way to customize this without templating, and any way to hack this (via command line options to show and hide tags) would be unsupported and could possibly change in the future. I would argue that you probably shouldn't do this even if you could.

From an end-user's perspective, there is significantly more value from consistency than there is from optimizing your own documentation's information flow. Knowing the order of information across documentation presented in a given template style gives users the ability to more quickly understand your docs. Moving things around may at first seem like you are making things easier to understand, but it's worth noting that users' mental model of your information layout will be colored by their experience with other documentation pages in other projects. Changing the order will likely confuse more than help.

[athityakumar]

@lsegal - Acknowledged. I'm not talking of changing the default templates. But, maybe supporting this order of sections via yardopts would be easier? Even though I can change the templates, they wouldn't get rendered as per that template in rubydoc.info.

[athityakumar]

BTW, thanks for replying this quick. 😄

[lsegal]

No problem!

I think ordering of the sections is the problem here. It's not a direct change to the template but it is a change to the way information is ordered on the page, and that could be seen as confusing to end-users. I'm not suggesting that it can't be done, I'm just suggesting that it's probably not a great idea given the underlying context users have when they visit your docs. For that reason, this to me seems like something that should not be configurable through command line.

Hope that helps!

[athityakumar]

Ah, understood that this might not be a solution preferred by the community. But can you please suggest a workaround for this, that would also work with rubydoc.info?

[lsegal]

@athityakumar the workaround depends on what problem you are trying to solve. Can you explain what you would use reordering for?

[athityakumar]

This is specifically for this YARD doc page. There are quite a lot of examples, after which the params information is being displayed. But IMO, it'd be better if the params information are shown first, and then followed by examples. Just to make sure that the user understands what exactly is going on, while passing which arguments.

[thomthom]

We've run into the same issue, were we used YARD to reformat the doc-comments. However, it appear to sort tags alphabetically. Where our original source code have had them organized differently (for example having examples last.)

I've played with monkey patching YARD with a plugin - but wish it was easier.