#193 awaiting-patch
David Brady

Publicly accessible methods and modules are marked :nodoc:

Reported by David Brady | March 11th, 2009 @ 09:31 PM

Trying to work with Webrat today, I found myself stopping Cucumber in the debugger and noodling around with the webrat object. Several objects and methods are present and accessible, but no documentation for them exists because they are marked as :nodoc: in the source code.

Some obvious examples:

Webrat::Locators::SelectOptionLocator#select_option Webrat::Locators::SelectOptionLocator <-- note that the entire class is also :nodoc:. This class adds methods to the base class, but there's no way to know this without reading the source code.

Webrat::XML <-- the whole module is nodocced. There are three methods inside the class also marked :nodoc:, but all the methods NOT marked :nodoc: won't show up either due to this directive.

Those are the ones I noticed digging through the source to find out how to express a matcher to Webrat in its own language. There are probably other examples of overzealous doc pruning.

Remember, even if you write no documentation, leaving a method or module documented will cause the method to appear in the RDoc. This tells people the method signature and, more importantly, that the method exists at all.

Thanks!

David

Comments and changes to this ticket

Please Sign in or create a free account to add a new ticket.

With your very own profile, you can contribute to projects, track your activity, watch tickets, receive and update tickets through your email and much more.

New-ticket Create new ticket

Create your profile

Help contribute to this project by taking a few moments to create your personal profile. Create your profile »

Ruby Acceptance Testing for Web applications.

Shared Ticket Bins

People watching this ticket

Attachments

Pages