lsegal/yard

Nameyard
DescriptionYARD is a Ruby Documentation tool. The Y stands for "Yay!"
LanguageRuby
Topics documentation
rdoc
ruby
ruby-documentation
tool
yard
yardoc
Watchers1,733
Forks378
Open issues104
Last push11/29/2021 10:06:40 PM +00:00
Github URLhttps://github.com/lsegal/yard
Clone URLhttps://github.com/lsegal/yard.git
SSH URL[email protected]:lsegal/yard.git

Most active issues

Topic# Comments
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 '.rb':3:

3: include Rails.application.routes.url_helpers


As far as I understand, "official" [solution](https://github.com/lsegal/yard/issues/575) 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
33
Hey.

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
32
For the following method:

ruby
class A
def a(b = -1)
end
end


This documentation is generated:

![screen shot 2015-08-15 at 10 11 19 am](https://cloud.githubusercontent.com/assets/1714/9289982/fff4d756-4335-11e5-86bb-9ed2b0bd02cd.png)

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


Read comments
23
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

ruby
class Foo
FOO = %i(foo, bar)
end


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:

ruby
> src = "%i(\na b c\n d e f\n)"
> p = YARD::Parser::Ruby::RubyParser.new(src, 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`:

ruby
> src = "%i(\na b c\n d e f\n)"
> p = YARD::Parser::Ruby::RubyParser.new(src, 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`): 0.8.7.6

I have read the [Contributing Guide](https://github.com/lsegal/yard/blob/master/CONTRIBUTING.md).


Read comments
22
The documentation(http://rdoc.info/github/tanoku/redcarpet/master/file/README.markdown) seems to suggest you can add support for PHP-markdown style tables by passing an option to `Markdown.new(…)`. It'd be cool if YARD could support this out of the box.


Read comments
22
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](https://github.com/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 RubyDoc.info fetch their data from Github repos.

Stefan


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

My **.yardopts** is right now:


--exclude README.md
lib/**/*.rb


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
20
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
20
see, https://groups.google.com/forum/?fromgroups=#!topic/yardoc/4etEJzgvRsE


Read comments
20
When trying to document a [JRuby-specific library](http://github.com/ruby-amqp/hot_bunnies) 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-0.8.6.1/templates/default/fulldoc/html/setup.rb:138:in `generate_method_list'
org/jruby/RubyBasicObject.java:1703:in `__send__'
org/jruby/RubyKernel.java:2209:in `send'
/Users/antares/.rvm/gems/[email protected]_bunnies/gems/yard-0.8.6.1/lib/yard/server/commands/list_command.rb:15:in `run'
/Users/antares/.rvm/gems/[email protected]_bunnies/gems/yard-0.8.6.1/lib/yard/server/commands/base.rb:95:in `call'
/Users/antares/.rvm/gems/[email protected]_bunnies/gems/yard-0.8.6.1/lib/yard/server/commands/library_command.rb:65:in `call'
/Users/antares/.rvm/gems/[email protected]_bunnies/gems/yard-0.8.6.1/lib/yard/server/router.rb:153:in `route_list'
/Users/antares/.rvm/gems/[email protected]_bunnies/gems/yard-0.8.6.1/lib/yard/server/router.rb:111:in `route'
/Users/antares/.rvm/gems/[email protected]_bunnies/gems/yard-0.8.6.1/lib/yard/server/router.rb:54:in `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
18