Our great sponsors
-
-
WorkOS
The modern identity platform for B2B SaaS. The APIs are flexible and easy-to-use, supporting authentication, user identity, and complex enterprise features like SSO and SCIM provisioning.
-
-
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.
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.
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.
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.
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.