Nail the Fundamentals : Documenting Using Yardoc (YARD)  
Tags: ruby, rails, documentation, doc
Published: 2019-10-11 23:09:18

**Disclaimer:** Nail the Fundamental series attempt to discuss good coding practices. Theses are personal industry lessons, taught by senior developers and software architects to enhance my skills. Most of the topics are general coding principles while some of them focus on specific coding language. 

If you are a junior developer, this is the right place for you as I aim to fill the gap between coding lessons taught in the academia and what happens in the the industry. If you are a senior developer, you can compare your methods with the ones practiced by different organizations in _the comments_.  

_________

Without further ado, In this tutorial we will look into YARD! 

![](https://media1.tenor.com/images/6305faf5259be354e2bd01b42ff6f875/tenor.gif?itemid=12003312)

Not that yard ... but YARD as in (Yay, A Ruby Documentation Tool). _YARD_ or _Yardoc_ is a documentation generating gem for the Ruby programming language. 

Before we jump into it, there is an important question to answer!

####_Why should I document?_

![](https://media.tenor.com/images/9c6976cc912cadac61f3049627b6366f/tenor.gif)

That is a fair question and I carried it when I started working in a development team. Some of the most important reasons to document your codes are:

- **You will be using them in 6 months:** Code that you wrote 6 months ago is often indistinguishable from code that someone else has written. Documentation is the key to understand the code's syntax and implementation. 
 
- **Increasing usability of the code:** If you writing a feature, the code most likely will be integrated into a bigger project. Therefore, you should document it to be easily understood and interpreted by other developers. 

- **Enhancing the On-boarding process:** In case of adding a new developer to your team or on-boarding a new department to use your internal tool, documentation reduces the time and effort for them to adapt the codebase.  

- **Simplifying the debugging:** Software logs help to indicate where to look for a bug and documentations allow pinpointing the issue in low-level.  

- **Assisting with test-cases:** Black-box testing which analyzes functionality of the software relies solely on the requirement specifications document of your code.

I hope by now you have enough reasons to start documenting your code. That definitely makes your code look more professional. so please ...

![](https://media1.tenor.com/images/7170a3a10863e930d233125b36d0283a/tenor.gif?itemid=10976391) 

 -----------------
## Why Yardoc?


_Yardoc_ is one of the well known ruby documentation tools and its benefits can be summarized as:  
- Can be hosted on personal DSL and private servers.
- Generates consistant documentation.
- Customizable documentation template (using markup language).
- Accepts metadata such as _tags_ along with the documentation (similar to Python, Java, and Objective-C).


## Installation



```bash 
# First make sure Rdoc is installed (dependancy on Ubuntu)
sudo apt-get install rdoc

# Mac users don't need to install rdoc since it is installed with
# the newest ruby installation.

# Next, install YARD using gem:
gem install yard

# Finally, to ensure YARD is installed
yard help
```

## Documentation Styles

### Most common tags:
- **@param** = Describes the _input parameters_ and their types (variable name can place before or after the type).
   - Example: `# @param [String] name Inputs the name of the user`
   - Example: `# @param [Numeric] age Inputs the age of the user`
   - Example: `# @param list [Array<String, Symbol>] the list of strings and symbols.`

- **@option** = In case you dealing with different _options_ for the same input (use this for hash or array-list).
   - Example: `# @param [Hash] area_parameter numeric Inputs `
   - Example: `# @option area_parameter [Integer] :length`
   - Example: `# @option area_parameter [Integer] :width`

- **@return** = Documents the _return-parameter_ from a method.
   - Example: `# @return [String] greeting message for the user.` 

- **@since** = Usually, `since` is used to show _app versions_.
   - Example: `# @since v2.0.0`

- **@raise** = Use it only if method raises any _exceptions_.
   - Example: `# @raise [ZeroDivisionError] expectation if dividing by zero`

- **@see** = Refer user to a _URL_ or _other class_ within the documentation for further explanation.
   - Example: `# @see www.yardoc.com`

- **@note** = Miscellaneous messages that are _low priority_.

- **@todo** = Miscellaneous messages that are _high priority_.

- **@example** = Demonstrates an _example_ of how to call the method.
   - Example: 

```ruby
# @example Raise an exception using a message from +debug_message+
#   raise AppDebug.fetch('job_number', app_name: 'ExampleApp')
```

### Common practice
- add the file `.yardoc` and `/doc` to your `.gitignore` sine they can be generated easily when needed.

- Document your private and protected methods. They will not be seen or used by the users but it helps other developers working on the same codebase. It is important to assure the private methods are not visible if you plan to publish the documentations. You can hide them in generating phase by:
`yardoc --no-private --protected`

- When documenting a method, first line holds the _Description_. Leave a blank `#` between the _description_ and _tags_. For Example:

```ruby
# this is the method's description. 
#
# @param [String] text_input input parameter
# @return [String] returns the printed text
def print_text(text_input)
    #some code ...
end
```

- Keep the order of _input parameters_ consistent with the _param_ orders. This results in easier flow for the reader. 

- Wrap the text with `+` to highlight
`+highlighted_text+`



## Hands-on Demonstration 

The code is available on [GitHub](https://github.com/erfankashani/Yardoc_Practice.git). clone the repository using:  

```bash
git clone https://github.com/erfankashani/Yardoc_Practice.git
```
Lets look into the files inside:

```bash 
cd Yardoc_Practice
nano practise.rb
```
![Alt Text](https://thepracticaldev.s3.amazonaws.com/i/2sguyyni98mdc1kr4zib.png)

Most of the _tags_ and the best practices are demonstrated in the code. Feel free to use this file as a reference for `yardoc`. Next step is to generate the documentation and spin-up the server.

### Generate Yardoc

1- Go inside of the repository which you are using
2- Create the documentation by: `yardoc <name_of_the_file>`, in our case:

```ruby
yardoc practise.rb 			
```

3- Run the web page on your local network (`Port:8808`):

```ruby
yard server 		
```

After this step, you will notice a new directory called 'doc'. This is where all the `HTML` and `css` files are kept to create the documentation webpage. Observe the documentations by typing `localhost:8808` in your address-bar of a browser. Take a look at the available methods by choosing `methods` option from the top left menu. You should see something like this:

![](https://i.imgsafe.org/5f/5feafca273.jpeg)

By now, I hope you have a good understanding of why we document and how we do it using 'yardoc'. As you follow these simple but effective practices mentioned in the series, you will notice your code quality's improvement. Take the first step by start documenting all your ruby codebases. Let's get ittt...

![](https://media1.tenor.com/images/6c7c9b29216de98af63ea842cf970d14/tenor.gif?itemid=8314803)


## Resources
- https://github.com/lsegal/yard
- https://gist.github.com/chetan/1827484 
- https://www.geeksforgeeks.org/differences-between-black-box-testing-vs-white-box-testing/