How to Use the Command 'yard' (with examples)

Yard is a documentation tool specifically designed for the Ruby programming language. It is a powerful resource typically used by Ruby developers to generate comprehensive project documentation. Yard parses your code and extracts the documentation to make it easily accessible and highly readable. This is crucial for maintaining clean and understandable code throughout the development process. More information can be found at Yard’s official site .

Use case 1: Create the documentation

Code:

yard

Motivation:

Creating documentation is a fundamental practice in software development. When working with Ruby, generating detailed and accessible documentation helps in understanding the codebase, facilitates team collaboration, and aids in onboarding new developers. By simply running yard, you can produce a structured and formatted set of documentation for your entire Ruby project. This command scans through the Ruby files in your project directory, extracting docstrings written in comments, and generates beautifully formatted HTML documentation.

Explanation:

• yard: This command is used to initiate the documentation generation process. When executed, Yard parses the comments and code structure within the Ruby files of your project, then converts them into a human-readable format. The command does everything automatically, scanning the entire project directory, so you don’t need to specify any additional parameters for basic documentation.

Example Output:

Running this command will generate an output similar to:

Files:          21
Modules:         5 (    5 undocumented)
Classes:         8 (    3 undocumented)
Constants:       5 (    0 undocumented)
Methods:        57 (   10 undocumented)
 97.37% documented

In addition to these statistics, the HTML documentation files will be created and stored in a doc directory within your project, providing a visual representation of your code structure.

Use case 2: Create the documentation and save it to one file

Code:

yard --one-file

Motivation:

Condensing all your documentation into one single file can be advantageous for various reasons. For instance, when you need to share the complete documentation with clients or other stakeholders who may not need access to a file directory, having it all in one file keeps things tidy and easily distributable. Additionally, in scenarios where system limitations require a minimal number of files, this command ensures you can meet such specifications without sacrificing documentation quality.

Explanation:

• yard: Initiates the documentation process as usual, parsing your Ruby files and generating documentation.
• --one-file: This flag specifies that all the generated documentation should be compiled into a single file rather than multiple HTML files across different directories. It’s a handy option for simplifying file management and distribution.

Example Output:

After running the command, you might receive output like:

Files:          21
Modules:         5 (    5 undocumented)
Classes:         8 (    3 undocumented)
Constants:       5 (    0 undocumented)
Methods:        57 (   10 undocumented)
 97.37% documented

Similar to the previous example, but now your project’s documentation will be consolidated into one file, typically named index.html, located in the doc directory.

Use case 3: List all undocumented objects

Code:

yard stats --list-undoc

Motivation:

Knowing which parts of your codebase lack documentation is crucial for maintaining high code quality. Undocumented code can become a significant bottleneck when trying to comprehend the function and structure, especially as the project grows and evolves. This command is invaluable as it allows developers to quickly identify gaps in documentation, prioritize them, and ensure they are filled. Using this tool can enhance usability and maintainability by ensuring that no part of your code is left unexplained.

Explanation:

• yard: Again, this initiates the process of analyzing the codebase.
• stats: This command option provides statistical information about your project’s documentation status, showing the overall documentation coverage.
• --list-undoc: This flag specifically directs Yard to output a list of all methods, classes, or modules that do not have associated documentation. It focuses only on elements lacking descriptions or comments, making it easier to pinpoint exactly where documentation is needed.

Example Output:

After running this command, the output might appear like:

[undocumented] Lib::UnseenMagic
[undocumented] Lib::HiddenGem
Files:          21
Modules:         5 (    2 undocumented)
Classes:         8 (    3 undocumented)
Constants:       5 (    0 undocumented)
Methods:        57 (   10 undocumented)

These outputs indicate specific undocumented objects within your project, helping you target your documentation efforts effectively.

Conclusion:

Utilizing Yard effectively can dramatically improve the quality of your Ruby project documentation. These options not only help generate clear and detailed documentation for sharing and distribution but also ensure that every aspect of your code is well-documented, helping you catch any undocumented sections quickly. As projects scale and teams grow, the importance of good documentation supported by tools like Yard becomes increasingly evident.