Home Other Writing documentation for Ruby on Rails projects with YARD

Writing documentation for Ruby on Rails projects with YARD

by admin

Writing documentation for Ruby on Rails projects with YARD
Good afternoon, hubs! Discovered that there is no article on the site about how you can organize the documentation process for Ruby on Rails projects.Let’s fix that problem.
This article will describe how, with the help of heme YARD you can write competent documentation for rail projects and automatically generate a document where this documentation will be presented in a presentable form. You can see an example of the documentation in the code of the site ValiIzRashki
First, a little theory. This might sound like captaincy to some, but my goal now is to convince those who don’t write documentation for code that it’s very useful and not at all hard. As a rule, documentation means a commentary on the code or a separate document where the site code is written.

Theory : why write documentation?

The answer is simple : to make the code clearer. Your colleague won’t have to distract you and ask a thousand questions, and you won’t have to rack your brains trying to remember the intricacies of your own code. In clear code it’s easier to find and eliminate bugs. It will also be easier for you to add a new feature to the code, which was just invented by a customer or a designer.

But the best commentary is the one that doesn’t need to be written?

It’s really necessary to write such understandable code that the amount of comments required to understand it is minimal. This is achieved by using variables with clear names, predictable and modular code structure, etc. Earlier I tried to write code without comments. But I soon understood that to spend two seconds on reading a comment to the code is more profitable than spending 5-10 seconds to read and understand even the most comprehensible code. Whichever way you look at it, it is much easier and more efficient to convey the gist of the code in normal language.

But it takes a long time to write documentation!

Not at all. With the method described here, it will take you an average of a minute to write the documentation for the code you just wrote. That minute will more than pay for itself the next time you go back to the code.
If you want more arguments on the plus side of documentation, you can read other articles by smart people on the subject, such as this one presentation. And we’ll move on to practice.

Practice : YARDstructured comments

At first, in my Ruby on Rails projects, I wrote comments without any particular structure. Before each method, I wrote briefly what was going on there. Then I realized that it would be convenient to describe, for example, the parameters that this method takes; as well as what it returns. The question came up, why not stick to a single comment template everywhere?
Writing documentation for Ruby on Rails projects with YARD
Found a gem YARD The idea is that you write comments to your code using a certain simple syntax, something remotely resembling xml/html. After that you execute the command which will create html files where your code and documentation will be described in a convenient format. The analogy is gem RDOC but I find its syntax more complicated.
Let’s set the gem

$ gem install yard

or add to Gemfile

gem 'yard'

and run bundle install.
Let’s take an example method from the website valiizrashki.ru

def try_to_evacuate(country_id)country = country.find(country_id)if country.allows_immigrants?evacuate!trueelsefalseendend

The method determines if you can immigrate to another country and evacuate. Let’s write it that way before declaring the method as a comment.

# Determines if you can immigrate to another country and evacuatedef try_to_evacuate(country_id)country = country.find(country_id)...

The method is called when the “roll” button is clicked. Let’s write it using the YARD tag @note , which is responsible for various extra data. The syntax looks like this :

@tag_name (space) tag content

If we want to fit several lines into one tag, we use tabulation

@tagnamefirst line of contentsecond line of content

Let’s write down the location information with the tag @note in the same place, before the method declaration :

# Determines if you can immigrate to another country and evacuate# @note Called when the "evacuate" button is pressed;def try_to_evacuate(country_id)...

Let’s write that the parameter takes a parameter with the tag @param In square brackets we write the data type of this parameter, after them we write the description of the parameter.

#param country_id [Integer] country id

Let’s write down exactly what this method returns with the tag @return Here we write the type of data to be returned in square brackets followed by a description of the value.

# @return [Boolean] if evacuated

To make it clearer, let’s write down an example of using this method. Let’s do it with the tag @example , in this case using tabs.

#example# try_to_evacuate(2)

We will also leave a link to the country model documentation using the @see so that you can jump there quickly.

# @seecountry

The result is this :

# Determines if you can immigrate to another country and evacuate# @param country_id [Integer] country id# @note Called when the "evacuate" button is pressed;# @example# try_to_evacuate(2)# @return [Boolean] if evacuated# @see Countrydef try_to_evacuate(country_id)country = Country.find(country_id)if country.allows_immigrants?evacuate!trueelsefalseendend

There are other tags in the YARD documentation that can be explored by this link.

Documentation time!

To make things incredibly mathematical, let’s create a configuration file in the project called yardopts with the following contents :

--private--protected-o doc/ruby

After that, in the terminal, go to your project folder and run the command

$ yard

The doc/ruby folder was created. Let’s open it in explorer and open _index.html there. In the browser, go to our method and see this :
Writing documentation for Ruby on Rails projects with YARD
It looks pretty good. And the link to the model method works.
Why did we make a settings file? So that we could run a simple command every time to generate the documentation The first two lines in the file are responsible for adding private methods to the documentation, and the third line designates the folder where the documentation appears.

Bonus : documenting coffeescript

Writing documentation for Ruby on Rails projects with YARD
For coffeescript they made a tool with similar syntax and functionality called codo I see no reason to limit the documentation to the ruby code and not write it for the scripts.
Example of a documented function that converts a number to radians :

# Conversion to radians# @param x [Integer] number# @return [Integer] radiansrad:(x) ->x * Math.PI / 180

Create a file in the root of the project codoopts and write there :

-o doc/coffee

After that, when running the command in the root of the project

$ codo

we will create documentation for coffeescript in the doc/coffee folder.
Done, you are adorable!


Finally, I want to say that even if you’re not going to use automatic documentation generation, I still advise you to start writing comments to the code in a structured form. This will make life easier for you and your colleagues!

You may also like