:nodoc: considered harmful

I may be weird in this, but I typically find that the best way to figure out how a Ruby gem works is to start picking through its RDoc. And for the most part, it couldn't be easier: do a gem install and hop over to http://localhost:8808/. It's good for an overview, it's good for reference. Being able to quickly scan an API, and then flick open the source when something isn't clear is great.

But then you find things like, say:

it_should_behave_like (*shared_example_groups)

Use this to pull in examples from shared example groups.
[show source]

# File lib/spec/example/example_group_methods.rb, line 64
      def it_should_behave_like(*shared_example_groups)
        shared_example_groups.each do |group|
          include_shared_example_group(group)
        end
      end

What, exactly, does "include_shared_example_group" do? From context of the API, something like look up strings in a table or constants in the namespace and include the associated module. Something like that. What exactly, though? For that, you'll need to dig into the source itself, which, while it's hardly impossible, is a bit of a roadbump in using the gem.

And this is for Rspec, which I generally like, in its featuritis-addled way. (Heaven protect us from the raft of testing frameworks out there. Wouldn't it be better to contribute to a known way than to re-implement everything over and over?) Don't get me started with trying to follow the thread through the Rails/Active/Action sausage factory.

Ultimately, what's the benefit to anyone of using :nodoc:? Either you're trying to reduce clutter in your API documentation (in which case, :nodoc: is not a panacea; it's hardly an aspirin) or you're trying to hide something hideous from the world.