Hey.

What I'm trying to achieve currently (on large codebase constantly changed by hundreds of people) is adding continuous integration check for YARD docs. What should be checked, ideally:

• level 0: No dumb errors (@param vs @params, documentation for parameter that is not there and so on);
• level 1: "You have changed file X, but it has undocumented methods/classes/modules now";
• ....more to come...

Let's skip levels 1+ for now completely (just a mention for future discussions) and focus on level 0. yard command currently has two levels of error reporting (amirite?): [error] (can't continue parsing this file) and [warn] (file is parsed but not everything is allright). Most of warn are indeed useful, so, it almost looks like "if there are any warnings, YARD CI step is failed", but there is one case, looking like this:

[warn]: in YARD::Handlers::Ruby::MixinHandler: Undocumentable mixin: YARD::Parser::UndocumentableError for class CodilityService
[warn]:     in file '<some_file_name>.rb':3:

    3: include Rails.application.routes.url_helpers

As far as I understand, "official" solution for this is "just ignore all warnings", which also gets rid of things like "Unknown tag @params", "Cannot resolve link to", "@param tag has unknown parameter name" which are pretty useful, to say the less.

So, to be honest, my "ideal" feature request would be:

• distinguishable warnings (and ability to turn them off by special comment tags?..);
• machine-ready output format (JSON?..), turned on by yardoc option;
• special option for "just check, no docs generation" (or is it yardoc --no-save?).

...but I'm open to any advice and suggestion :)

(Also, I'm not afraid and even willing to provide PRs and other contributions, if it could be appropriate.)