Documentation generation ignores visibility and :nodoc:

[MikeTaylor]

So I am getting documentation generated for the private classes and members in my project (ScottKit).

[zapnap]

:nordoc: is not supported by YARD. Private method documentation can be toggled with --private; please check the yard docs for more information http://yardoc.org/docs/yard/file:README.md

[MikeTaylor]

But is there any way to have --private used when generating the documentation of my module on rdoc.info?

And ... not supporting :nodoc: seems like ... a surprising choice. Is there any likelihood of that ever changing?

Otherwise (and I know it's cheeky of me even to ask this) do you know if there are other rdoc.info-like sites that use actual rdoc rather than YARD?

Many thanks.

[zapnap]

You can pass options to the YARD processor by creating a .yardopts file in your repository, which we'll process at document creation time. Just add the file and separate the options you want to use by whitespace (note that we strip certain options that may be dangerous, like -e)

The :nodoc: omission is an intentional choice in YARD, and isn't likely to be changed. See http://github.com/lsegal/yard/issues/issue/34 for a discussion about the subject.

I don't know of any sites that autogenerate straight rdoc instead of yardoc. In my (personal) opinion, RDoc the project (rather than rdoc the concept), is pretty busted and YARD is really the way to go for modern Ruby documentation needs. That's just our position on the matter though. I think if you take some time to read over the YARD documentation you'll find it's a lot more featureful and useful than RDoc ever was. The private API stuff, in particular, is pretty powerful.

[MikeTaylor]

Thanks, I really appreciate your taking the time here. I am new to Ruby after a decade of Perl, and still feeling my way through the mazes of twisty little repository hosting services, build automation packages and inline documentation formats.

I'll try the .yardopts file and see if that helps.

Unfortunately, yard itself does not work on my system: I installed it using gem1.9 (and ignored some failures in generating its own rdoc documentation, caused I think by the rdoc parser not being able to handle "alias [] create" in yard/core_ext/hash.rb -- I doub this is related to my more fundamental problem).

Now when I run /var/lib/gems/1.9.0/bin/yardoc, I see:

/var/lib/gems/1.9.0/gems/yard-0.5.3/lib/yard/parser/ruby/ruby_parser.rb:100:in `block (1 levels) in class:RubyParser': /var/lib/gems/1.9.0/gems/yard-0.5.3/lib/yard/parser/ruby/ast_node.rb:49: syntax error, unexpected ':' (SyntaxError) KEYWORDS = { class: true, alias: true, lambda: t... ^ (And then a cascade of subsequent errors caused by the parser being confused by this first one.)

Sure enough, when I try to run that file in isolation, it's syntax error:

$ ruby1.9 ast_node.rb ast_node.rb:49: syntax error, unexpected ':' KEYWORDS = { class: true, alias: true, lambda: t... ^ I googled for help, but couldn't find anything. Have you ever seen this?

I am using Ruby 1.9.0, installed from the standard package under Ubutnu 8.10.

(I realise we are now a looong way from the nominal subject of this bug -- sorry about that.)

[zapnap]

I haven't seen that personally, but you may want to open an issue on the YARD project itself (lsegal/yard on github). Loren is usually really quick to respond to that kind of stuff.