The Why and How of Yardoc

Inching Along the Never Ending Path of Improving of Documentation.

Even if you decide never to write a single line of a manuscript, you will improve your reading, thinking, and other intellectual skills just by doing everything as if nothing counts other than writing.

—Sönke Ahrens, How to Take Smart Notes

Over the last 5 months at Forem, I’ve started adding lots of inline documentation to Forem’s Ruby code. When I started, I noticed we had a great developer documentation but we didn’t have much inline documentation. I made an implicit decision that as I wrote worked on code, I would add inline documentation to the places I touched.

I’ve long used the YARD format and chose to use that as my documentation syntax. I suppose I didn’t check with anyone on this decision and slowly started adding documentation. I want to use this post to synthesize my implicit decision and the benefits of using Yard as the documentation format.

Or another way to look at it, how writing documentation helps me and how choosing YARD helps you (and me).

How Writing Documentation Helps Me

There is a secret bond between slowness and memory, between speed and forgetting.

—Milan Kundera, Slowness

In Slowing Down to Synthesize, I wrote about taking the time to write. In that post I wrote about writing with pen and paper. The act of shifting from pen to paper changes my context.

That important context shift can sometimes get lost when I’m only switching tabs or buffers on my computer. Once, long ago, I thought about writing a book. One section was a reflection on the mental contexts that I need to consider.

When I write documentation, I’m shifting from resolving the problem to describing the problem, resolution, and intention.

That deliberate shift helps me step back from implementation and into design and communication considerations. If I can explain it using prose, I can almost certainly knock out a solution.

When I start with the documentation, I’m framing my approach; having a dialogue about what I’m trying to accomplish. Sometimes that documentation is “code comments” other times it’s writing up an RSpec test.

When I start with the code, I use my documentation writing as the time to synthesize what I wrote. To explain and instruct my future self (as well as other folks engaging with this portion of the code base).

This draws from the principles of the Feynman Technique; namely the best way to learn something is to teach about it. And one way to teach is to write.

For further reflections, I point you to On Writing Documentation.

How Using Yard Helps You and Me

Documentation is a love letter to your future self.

As I’ve moved through my career as a software developer, I’ve accepted that documentation is imperfect and sometimes incorrect. But it provides another explanation of what’s happening in the code.

The code says what the system does, but to synthesize intent of the system the code provides only one perspective. The variety of documentation generates as part of delivering that code provides a richer context.

If a developer took the time to describe the purpose of a class, I can use that to help me triangulate my interactions with that class.

Browse-able Documentation

You can generate local documentation. In Forem’s root directory, you can run yard to generate the doc directory. Then open the doc/index.html file in your browser. There is a live server, but I tend to generate the docs and navigate the static files.

Some useful features of YARD generated browse-able documentation are:

Showing known sub-classes

What all inherits from Admin::ApplicationController?

Listing inherited methods

What methods does Admin::ApplicationController inherit from ApplicationController; this does not cross boundaries of repositories (without further configuration)

Showing what’s in name-spaces

Consolidates all classes in the Articles name-space.

These are some of the out of the box things. As a developer looking to contribute to Forem’s code-base, I find usefully these alternate views of the code.

And as we move along with developing Forem, I could see us further committing to generating and publishing this low-level documentation along side our higher level documentation. Ruby on Rails has both api.rubyonrails.org and guides.rubyonrails.org; these are complimentary views into how to work with Rails.

Language Server Protocol

Many Integrated Development Environments (IDEs) and text editors provide code completion support. The emerging standard is to do so via the Language Server Protocol (LSP). In a broad sense, this a client / server structure.

The IDE and text editor operate as the client, and for the current context they request information from the associated language server. The server handles the request and sends the response back. And with the protocol, each language server conforms to a standard interface (though some implement more features than others).

To make the general specific, when I’m in Emacs and I “hover” over a class name in a Ruby file, after a brief pause, I see the top-level documentation for that class. Or when I start typing a method name, I can prompt for auto-complete. The details that “pops up” is information provided by the language server.

In Ruby’s case, the language server is Solargraph; which parses the YARD documentation to provide the details. For Emacs, I’m using the eglot.el package to provide Language Server Protocol support. Others in Emacs use lsp-mode.el. The Solargraph homepage has a supported editors section that provides guidance on integrating Solargraph with VSCode, Atom, Sublime Text, Eclipse, Vim, and Emacs.

Some Screenshots

The below screenshot demonstrates what pops up when my cursor is on the method ApplicationController#require_user_in_good_standing!. In the bottom portion of the screenshot is the rendering of the doucmentation for that method. Kind of nice to see that level of detail.

The following screenshot shows the auto-completion for method names. It is annotated with parameters and return values. Some of those methods are more richly annotated than others; that's a function of how they are documented.

Quick Course in Yard

When I’m writing YARD docs, I refer to the Tags Overview — Documentation for yard page. In particular the Tag List section. There I find the examples of existing tags, and go about documenting things.

I also created a few snippets to help me easily and quickly add well formed documentation. In my editor when I type @p followed by TAB, it expands into the @param tag format and guides me on filling out that documentation. In other words, I’m always configuring my editor to help me write more of what I write.

Conclusion

As I look at my career, I have long-maintained that I am a better developer because I started writing tests and thinking about what they are trying to convey. Tests are documentation about how the developers expect the system to operate.

The next stage of my development has been a stronger commitment to writing low-level documentation. To provide way-finding for my future self and others. Documentation is my chance to articulate the intention of the code I’m writing. The “why” if you will.

To explain something in a different way helps me gain confidence in my understanding.

And I use YARD as the syntax for helping me learn more about the code I’m writing. A happy byproduct, with the help of Language Server Protocol is that it helps me write better