Nail the Fundamentals : Documenting Using Yardoc (YARD)

#ruby #rails #documentation #doc

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!

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?

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 ...

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

# 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:

# @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:

# 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. clone the repository using:

git clone https://github.com/erfankashani/Yardoc_Practice.git

Lets look into the files inside:

cd Yardoc_Practice
nano practise.rb

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:

yardoc practise.rb

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

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:

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...