YARD documentation curveballs

Ruby on Rails
1

I’ve been working on developing a Rails engine for the past 7 months, and the only documentation so far has been comments mixed in with the code. I’m self-taught and I’m my employer’s only developer, so I have no example to follow for how to document this gem properly.

I did some searching and it looks like YARD is favoured by a lot of the Rails community (correct me if I’m wrong). I’ve documented almost all of my methods and classes using YARD, and although I’ve been successful in generating the documentation locally/running a local documentation server, there are a still a few things that I can’t seem to Google an answer to:

  1. Some things don’t seem to make sense to document. For example, it seems silly to provide a docstring for the ApplicationController class (since its function is an inherent part of Rails), though it does make sense to document its methods. However, leaving things like ApplicationController undocumented causes YARD to list them as such, and display less than 100% coverage. What’s a good way of dealing with these things that don’t need documentation?
  2. Does it make sense to provide documentation for simple Rails controllers? Given the convention over configuration approach of Rails it seems pointless to just add “displays all [model name]” to all #index methods, etc. since by convention that’s what we’re expecting anyway. Then again, not documenting them causes YARD to complain again, just like in #1.
  3. I can’t seem to find any consensus (or even information) on how to document the params hash for Rails controller actions. I’m using @param hash_key at the moment but this causes YARD to provide a warning that the method doesn’t take those parameters.
  4. The engine will be hosted on Github in a private repo (it’s an internal project). I don’t like the idea of checking the generated documentation into the repo in order to display it on Github, and I suspect this would break the generated links anyway. Is there a way for a private repo have YARD documentation available without having to clone the repo and run yard doc?
2

I did some searching and it looks like YARD is favoured by a lot of the Rails community.

Yep, Yard is still the most popular choice for documenting Ruby code.

For example, it seems silly to provide a docstring for the ApplicationController class.

Agreed; you can safely assume Rails developers will know what this is.

However, leaving things like ApplicationController undocumented causes YARD to list them as such, and display less than 100% coverage.

I wouldn’t worry about getting 100% coverage, since you’ve already made the decision that some things aren’t worth documenting. If you want to double check that you’ve documented everything worthwhile, you can run yard stats --list-undoc to see what’s currently missing documentation.

Does it make sense to provide documentation for simple Rails controllers?

I don’t generally do this, but it might be worthwhile in an engine. A single sentence stating which page or resource the controller is in charge of would suffice. It may also be more useful to just list these controllers and responsibilities out in the README. Far more people will scan README documentation than will dive into documentation for individual modules.

I can’t seem to find any consensus (or even information) on how to document the params hash for Rails controller actions.

Yeah, I’m not sure how you’d do this. Yard doesn’t have tags for this, but you can add custom tags. I don’t think it would be worth it, though. If you’re following conventions, the expected parameters should be obvious.

Is there a way for a private repo have YARD documentation available without having to clone the repo and run yard doc?

You can make a rake task to generate the documentation and push it to S3, which will happily serve static HTML. It may be easiest to have CI run this task, so that your documentation gets updated whenever you merge into master.

3

Thanks for the reply. It’s good to know that I’m not totally off the mark for thinking some things don’t need documentation.

That’s a very useful command! Unfortunately as the list of things I deliberately leave undocumented grows, the list produced by --list-undoc becomes hard to scan for things that do actually need to be documented. As a solution I’ve started giving ‘undocumented’ things a docstring of :nodoc: or something similar just to make it clear that they’re not supposed to be documented and to avoid having them show up in the --list-undoc list.

Hmmm, I find it strange that a part of Rails this ubiquitous wouldn’t be supported by YARD. I guess it makes sense though, since as you pointed out the expected parameters are usually obvious due to convention. Unfortunately this engine deviates from convention in a few ways, but I guess that’s when custom tags come in handy - thanks for that link.

[quote=“jferris, post:2, topic:3944”]
You can make a rake task to generate the documentation and push it to S3, which will happily serve static HTML. It may be easiest to have CI run this task, so that your documentation gets updated whenever you merge into master.[/quote]

That’s brilliant, and actually points me in the direction of a whole bunch of different options for this. It’s probably about time I learned about rake tasks anyway :slight_smile: