Yard-Junk: get rid of junk in your YARD docs!

Yard-Junk is yard plugin/patch, that provides:

• structured documentation error logging;
• documentation errors validator, ready to be integrated into CI pipeline.

Showcase

Let's generate the docs for the rom library.

Things to notice:

• irregular and frequently approximate addresses (in file 'core/lib/rom/types.rb':9, in file 'core/lib/rom/global.rb' near line 41, sometimes in separate line, sometimes inline), hard to jump-to with any tool;
• a lot of ununderstood metaprogramming (grep for "Undocumentable mixin") -- nothing to fix here, but YARD still notifies you;
• verbose and not very informative errors (look at that "Undocumentable mixin" -- and then grep for "The proxy Coercible has not yet been recognized." and compare).

Things to notice:

• Regular output style with clearly recognizable addresses (and fixed to point at actual line with the problematic tag, not the method which tag is related for);
• Error classes, allowing grouping, grepping, and configuring (notice no "Undocumentable xxx" errors: I've just configured yard-junk to drop them for this repo);
• Usage of Ruby's bundled did_you_mean gem to show reasonable suggestions:

  Unknown tag @raises. Did you mean @raise?
  @param tag has unknown parameter name: options. Did you mean `new_options`?

• Rephrased and cleaned up messages.

It is basically the same as above, and:

• sorted by files/lines instead of "reported when found" approach;
• with short stats at the end;
• returning proper exit code (0 if no problems/parsing errors, non-0 otherwise), which allows yard-junk to be integrated into CI pipeline, and control that new PRs will not screw docs (forgetting to rename parameters in docs when they are renamed in code, for example).

As a nice addition, yard-junk command uses its own links to code objects resolver, which is 10x faster (and, eventually, more correct) than YARD's own approach to resolve links when rendering docs.

Usage

It is a yard-junk gem, install it as usual, or add to your Gemfile.

Better logs

Add this to your .yardopts file:

--plugin junk

After that, just run yard or yard doc as usual, and enjoy better logs! You can also setup JunkYard logs by passing options (in the same .yardopts):

--junk-log-format FORMAT_STR
--junk-log-ignore ERROR_TYPE1,ERROR_TYPE2,...

Format is usual Ruby's #format method with named fields:

• message -- error message;
• file -- error file;
• line -- error line;
• type -- error type.

Default format is %{file}:%{line}: [%{type}] %{message}, as shown above.

--junk-log-ignore option allows to ingore error classes by their type names (shown in logs in []). By default, Undocumentable error is ignored: it is produced as metaprogramming pieces of code like

attr_reader *OPTIONS

or

include Rails.routes

...and typically have no way to fix, while polluting logs with a lot of, well, junk.

Standalone docs check

Just run yard-junk command after gem is installed. Optionally, you can setup "formatters" to use:

• text formatter: suitable for console, sparse colorized output;
• HTML formatter: suitable as CI artifact, readable in browser.

Examples:

• yard-junk (default run, outputs text to STDOUT);
• yard-junk --text (same as above);
• yard-junk --text logs/yard.log (set the output path);
• yard-junk --text --html build-artifacts/junk-yard.html (several formatters at once: text to console, HTML to file).

You can also specify pathes to report (useful when working on large codebases, when you want to check only your recent piece of work):

yard-junk --path some/path/
yard-junk --path other/path/*sample*.rb
yard-junk --path specific/path.rb
yard-junk --path several,different/*.rb,patterns.rb

Note that yard-junk would parse the pathes that set in .yardopts as usually, and then filter report by pattern specified.

Rake task (integrating in CI)

Add this to your Rakefile:

require 'yard-junk/rake'
YardJunk::Rake.define_task

and then run it (or add to your .travis.yml) as

rake yard:junk

The Rake task also takes formatter arguments, at task-definition time:

YardJunk::Rake.define_task(:text) # default
YardJunk::Rake.define_task(text: 'logs/yard.log') # text to file
YardJunk::Rake.define_task(:text, html: 'build-artifacts/junk-yard.html') # text to STDOUT, html to file

Reasons

Small problems in docs lead to a decrease in readability and usability. But it is hard to check for all those problems manually due to YARD's cumbersome output, and lack of CI-ready doc checking tools.

The idea of a regularly structured logger was initially proposed as an enhancement for YARD itself, and even some steps were made by YARD's author in that direction, but the idea was abandoned since.

Therefore, this independent tool was made.

Caveats

Sometimes YARD doesn't provide enough information to guess in which line of code the problem is; in those cases yard-junk just writes something like file.rb:1 (to stay consistent and not break go-to-file tools).

Roadmap

• Docs for usage as a system-wide YARD plugin;
• Docs for internals;
• Documentation quality checks as a next level of YARD checker (#14).

Some examples of problems found in popular gems:

NB: All of those are excellent libs! The showcase is of "how hard it is to maintain docs quality", not of "how ignorant other programmers are".

Authors

• Victor Shepelev
• Olle Jonsson

License

MIT