DescriptionYARD is a Ruby Documentation tool. The Y stands for "Yay!"
Topics documentation
Open issues104
Last push11/29/2021 10:06:40 PM +00:00
Github URL
Clone URL
SSH URL[email protected]:lsegal/yard.git

Most active issues

Topic# Comments

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 '.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.)

Read comments

While trying to document really large codebase, I stuck with

yard-0.9.5/lib/yard/parser/ruby/ast_node.rb:198:in `children': stack level too deep (SystemStackError)
from /media/storage/home/zverok/.rvm/gems/ruby-2.3.1/gems/yard-0.9.5/lib/yard/parser/ruby/ruby_parser.rb:650:in `freeze_tree'
from /media/storage/home/zverok/.rvm/gems/ruby-2.3.1/gems/yard-0.9.5/lib/yard/parser/ruby/ruby_parser.rb:652:in `block in freeze_tree'
from /media/storage/home/zverok/.rvm/gems/ruby-2.3.1/gems/yard-0.9.5/lib/yard/parser/ruby/ruby_parser.rb:650:in `each'
from /media/storage/home/zverok/.rvm/gems/ruby-2.3.1/gems/yard-0.9.5/lib/yard/parser/ruby/ruby_parser.rb:650:in `freeze_tree'
from /media/storage/home/zverok/.rvm/gems/ruby-2.3.1/gems/yard-0.9.5/lib/yard/parser/ruby/ruby_parser.rb:652:in `block in freeze_tree'
from /media/storage/home/zverok/.rvm/gems/ruby-2.3.1/gems/yard-0.9.5/lib/yard/parser/ruby/ruby_parser.rb:650:in `each'
from /media/storage/home/zverok/.rvm/gems/ruby-2.3.1/gems/yard-0.9.5/lib/yard/parser/ruby/ruby_parser.rb:650:in `freeze_tree'
from /media/storage/home/zverok/.rvm/gems/ruby-2.3.1/gems/yard-0.9.5/lib/yard/parser/ruby/ruby_parser.rb:652:in `block in freeze_tree'
... 10163 levels...
from /media/storage/home/zverok/.rvm/gems/ruby-2.3.1/bin/yardoc:23:in `load'
from /media/storage/home/zverok/.rvm/gems/ruby-2.3.1/bin/yardoc:23:in `
from /media/storage/home/zverok/.rvm/gems/ruby-2.3.1/bin/ruby_executable_hooks:15:in `eval'
from /media/storage/home/zverok/.rvm/gems/ruby-2.3.1/bin/ruby_executable_hooks:15:in `

Unfortunately, codebase belongs to proprietary project, so I can't share it. Neither I can narrow the case (to current moment). I turned on `--debug` option to see the filename on error, and there is nothing special in this file. Moreover, when I comment it out, the very same error emerges in the next file (and if I comment out that one, in the next, and so on).

What can I do for debugging/understanding? Is that possible that size of codebase could be a limitation/fatal problem for YARD?..

Read comments
For the following method:

class A
def a(b = -1)

This documentation is generated:

![screen shot 2015-08-15 at 10 11 19 am](

Note the extra bracket: `a(b = -1))`

Read comments
When using Yard on a class that has a constant declared with `%i`, the constant does not include the `%i` when viewing the generated documentation.
## Steps to reproduce

Create a class such as

class Foo
FOO = %i(foo, bar)

When viewing the documentation for this class, the constant FOO appears does not include the initial `%i(` characters.
## Actual Output

I'm not familiar with the parser, but borrowing from the Ruby parser specs:

> src = "%i(\na b c\n d e f\n)"
> p =, nil).parse.root.first
> p.jump(:qwords_literal).source
=> "a b c\n d e f"

leaving the `%i` out
## Expected Output

A similar example using `%w`:

> src = "%i(\na b c\n d e f\n)"
> p =, nil).parse.root.first
> p.jump(:qwords_literal).source
=> "%w(\na b c\n d e f\n)"

Thank you! I've written some specs that replicate the issue and could put together a PR if you like.
## Environment details:
- OS: OS X 10.11.6
- Ruby version (`ruby -v`): 2.3.0
- YARD version (`yard -v`):

I have read the [Contributing Guide](

Read comments
The documentation( seems to suggest you can add support for PHP-markdown style tables by passing an option to `…)`. It'd be cool if YARD could support this out of the box.

Read comments
In my README files I use features from Github Flavored Markdown, such as code highlighting and awareness for underscores inside a word, but YARD does not recognize them.

Adding [github-markup]( as a markup provider to .yardopts

`-M github-markup`

resulted in an error:

[error]: Invalid markup type 'markdown' or markup provider (github-markup) is not registered.

yard-0.7.3/lib/yard/templates/helpers/html_helper.rb:70:in `html_markup_markdown': undefined method `new' for nil:NilClass (NoMethodError)

Is there a way to make YARD parse Github Flavored Markdown? If not, I would suggest this as a new feature, especially because services like fetch their data from Github repos.


Read comments
I've tried several ways of skipping the **** file without success.

My **.yardopts** is right now:


Every single time, a file called **file.README.html** is created, and what is worse, **index.html** will render it by default. I also remove the **doc** directory every time, so the file is not a remanent from the last invocation.

The parser is working, according to this:

$ yardoc --debug
[debug]: Parsing ["lib/**/*.rb"] with `ruby` parser
[debug]: Parsing lib/aio.rb
[debug]: Parsing lib/aio/board.rb
[debug]: Parsing lib/aio/sketch.rb
[debug]: Parsing lib/aio/errors.rb
[debug]: Parsing lib/aio/helpers.rb
[debug]: Parsing lib/aio/constants.rb
[debug]: Serializing to .yardoc/objects/root.dat

Is this a bug? How can I skip it?

Read comments
I removed most of the warnings that show up during testing and when yardoc is run. There are still a couple of stragglers that I was not able to track down.

Read comments

Read comments
When trying to document a [JRuby-specific library]( with YARD, I'm hitting

[2013-06-02 09:01:44] ERROR NoMethodError: undefined method `prune_method_listing' for #
/Users/antares/.rvm/gems/[email protected]_bunnies/gems/yard- `generate_method_list'
org/jruby/ `__send__'
org/jruby/ `send'
/Users/antares/.rvm/gems/[email protected]_bunnies/gems/yard- `run'
/Users/antares/.rvm/gems/[email protected]_bunnies/gems/yard- `call'
/Users/antares/.rvm/gems/[email protected]_bunnies/gems/yard- `call'
/Users/antares/.rvm/gems/[email protected]_bunnies/gems/yard- `route_list'
/Users/antares/.rvm/gems/[email protected]_bunnies/gems/yard- `route'
/Users/antares/.rvm/gems/[email protected]_bunnies/gems/yard- `call'

when I try to open the list of classes. I use Kramdown for the renderer but the exception
seems to originate in an unrelated part of the codebase.

Read comments