Any way to ignore Undocumentable?

[jjb]

i want to run yard doc --fail-on-warning --no-output in CI and confirm success

i have several instances of undocumentable code

one instance is this in a rails model, also the subject of this 12-year-old SO question which i just put a bounty on 😄

include Rails.application.routes.url_helpers

is there any way to ignore or document these so that there are no warnings?

i researched high and low before writing this, i hope i didn't miss something.

thanks for a great project!

[jjb]

in case helplful to someone finding this, here's what i'm trying in CircleCI

set +e # do not exit right away if a command fails https://circleci.com/docs/configuration-reference/#default-shell-options
yard doc --fail-on-warning --no-output &> yard_out
grep "\[warn\]" yard_out | grep -ivq undocumentable
if [ $? -eq 0 ]; then # grep found a warning that is not undocumentable? that's bad
  echo "IMPORTANT: Do not try to fix 'Undocumentable' errors, only fix the others"
  echo
  cat yard_out
  echo
  echo "IMPORTANT: Do not try to fix 'Undocumentable' errors, only fix the others"
  exit 1
fi
cat yard_out # all good! show output and exit success

[lsegal]

is there any way to ignore or document these so that there are no warnings?

This is a bit of a loaded question. There is no way to retain the same syntax and not have YARD display warnings. By the same token, if you do not want warnings to fail your CI build, you should not use the built-in --fail-on-warning option. YARD's fail-on-warning option is intentionally simplistic, since YARD's core codebase itself is not a documentation linter; the fail on warning option is a convenience to provide an error code if any warning text was printed. tl;dr, fail-on-warning does not allow for customization.

In general, the solution to providing documentable code is to reduce your use of dynamic calls such as the one you've listed. In almost all cases, there is a non-dynamic alternative to dynamic Ruby syntaxes. In the case of your specific example, you could use Rails.application.routes.url_helpers.YOUR_ROUTE directly. Another Rails specific solution would be to wrap the include statement inside of a Concern:

module WithRoutes
  extend ActiveSupport::Concern

  included do
    include Rails.application.routes.url_helpers
  end
end

class MyController < ApplicationController
  include WithRoutes
end

This will bypass top-level inclusion in the YARD parser.

If you do not want to change your syntax, the solution you've come up with is basically the simplest "recommended" path as far as implementing simple custom linting in CI. If you want something a little more robust, you can consider using YARD extensions, like overriding YARD::Logger#warn to do this type of parsing in Ruby, or via an extension to specific handlers. The latter would afford you a lot more flexibility about what type of code is allowed and when, for example:

# yard_extensions/ignore_rails_mixin.rb
module IgnoreRailsMixin
  def process
    super
  rescue YARD::Parser::UndocumentableError => e
    raise e unless statement.last.source.start_with?("Rails.")
  end
end

YARD::Handlers::Ruby::MixinHandler.prepend(IgnoreRailsMixin)

You can use the above via yard -e yard_extensions/ignore_rails_mixin.rb or by adding -e yard_extensions/ignore_rails_mixin.rb to your .yardopts.

[jjb]

Wow, thank you so much for these solutions!

[jjb]

Here's what I came up with, I couldn't figure out a way to get it into the top level process method, since it's done with metaprogramming

# https://github.com/lsegal/yard/issues/1542
module YardIgnoreUndocumentable
  def process
    super
  rescue YARD::Parser::UndocumentableError => e
    puts '😎'
  end
end

YARD::Handlers::Ruby::MixinHandler.prepend(YardIgnoreUndocumentable)
YARD::Handlers::Ruby::AttributeHandler.prepend(YardIgnoreUndocumentable)
YARD::Handlers::Ruby::MethodHandler.prepend(YardIgnoreUndocumentable)

and then running this in CI

yard doc -e lib/yard_extensions/ignore_undocumentable.rb --fail-on-warning # do not add --no-output