Documentation
Explore techniques to ensure code consistency by creating clear and accessible documentation in Elixir. Learn to use built-in attributes, automated tools like ExDoc for generating readable docs, and InchEx for measuring documentation coverage. Understand the difference between documentation and comments, and how to support team collaboration and onboarding with quality documentation.
We'll cover the following...
Need for documentation
We’ve discussed strategies for how to enforce consistent coding standards and typespecs. These are arguably objective metrics. Documentation, on the other hand, is essential to maintaining a consistent codebase, but since it’s for human readers, it’s much more subjective.
For experienced developers, documentation of public and common interfaces allows rapid ramp-up and removes friction. For new adopters, documentation is essential. Documentation will help them internalize how the new application works and serves as the first point of communication between the code producer and consumer. In this lesson, we’ll look at ways to help automate aspects of our documentation. We’ll look at tools to help build tested examples into our code and check the health of our documentation with a single automated metric.
The Elixir team emphasizes first-class documentation support. The documentation for the application should be easy to write and easy to read. For writing, use the @doc and @moduledoc attributes. ...