yard
yard copied to clipboard
Generate machine-readable report of undocumented entities with their file + line
I'd like to use yard
to feed a linter-style report of undocumented functions. This would allow me to parse the result and surface file & line annotations in an editor or on GitHub.
It looks like the basic components of this already exist: I can run yard stats --list-undoc
and get some output that includes
Undocumented Objects:
(in file: path/to/file.rb)
MyModule::MyClass::MY_CONSTANT
I can parse this output for the entity names, then cross-check them with the output yard doc --list
, which looks like
/path/to/file.rb:3: MyModule::MyClass
/path/to/file.rb:345: MyModule::MyClass::MY_CONSTANT
But this seems clumsy, not to mention it would be brittle -- sensitive to any changes in the output formats of either command. What I'd like is an option to produce (directly) a machine-parseable report that includes the fields file
, line
, entity type
(attribute, module, class, function, etc), and name
. This could be something like a comma-separated or pipe-separated string (1 message per line) or something more structured, like JSON.
YARD typically doesn't have porcelain style output because if you need specific structure to be parsed by "machine", it's easy enough to use its programmatic API to access via standard irb / Ruby scripting directly:
require 'yard'
YARD::CLI::Yardoc.run('-n', '-q')
undoc = YARD::Registry.all.select {|o| o.docstring.blank? }
undoc.each do |obj|
puts "#{obj.file}:#{obj.line}: #{obj.type} #{obj.path}"
# but really your tool can just use obj right here.
end
CodeObjects are documented via https://rubydoc.info/gems/yard/YARD/CodeObjects/Base