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:
- Some things don’t seem to make sense to document. For example, it seems silly to provide a docstring for the
ApplicationControllerclass (since its function is an inherent part of Rails), though it does make sense to document its methods. However, leaving things like
ApplicationControllerundocumented 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?
- 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
#indexmethods, 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.
- I can’t seem to find any consensus (or even information) on how to document the
paramshash for Rails controller actions. I’m using
@param hash_keyat the moment but this causes YARD to provide a warning that the method doesn’t take those parameters.
- 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