Generate machine-readable report of undocumented entities with their file + line

[ianfixes]

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.

[lsegal]

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