Bug #4665


Add nodoc comments for Set methods

Added by phiggins (Pete Higgins) about 11 years ago. Updated over 10 years ago.

Target version:
ruby -v:


Set#flatten_merge and Set#do_with_enum are called internally by other Set methods. Add nodoc comments to them so they don't show up in the list of undocumented things.


add_nodoc_to_set.diff (560 Bytes) add_nodoc_to_set.diff Patch diff. phiggins (Pete Higgins), 05/11/2011 11:38 AM

Updated by lsegal (Loren Segal) about 11 years ago

I noticed that Set#do_with_enum is already marked as private-- most likely so that it does not show up in documentation (at least using the default rdoc arguments). Therefore, is :nodoc: really necessary here? I point to which seems to ignore private methods, including #do_with_enum.

As far as Set#flatten_merge goes-- perhaps instead of marking it as :nodoc: it should be made private. This way it will also be ignored from docs.

That said-- perhaps the list of undocumented items should be updated to exclude private methods, which are currently already excluded from docs. If not, perhaps :nodoc: isn't the right answer and real docs should be added, since :nodoc: doesn't actually add any documentation here, so the change in doc coverage would just be superficial. Does anyone object to having docs for the internal methods? I wouldn't mind writing something.

Updated by phiggins (Pete Higgins) about 11 years ago

Hi Loren,

Rdoc excluding private methods in its output but considering them undocumented sounds like an issue with rdoc. I'll take that up with Eric.

Set#flatten_merge needs to remain protected so that it can be called on other instances of Set. Take a look at Set#flatten for the example of that. I'm not sure it's useful outside that context which is why I favored marking it :nodoc: rather than adding actual documentation. That's just my opinion though, so feel free to document this function if you like.

Updated by drbrain (Eric Hodel) about 11 years ago

By default, Ruby generates ri with --all so private methods will be picked up.

Method visibility is up to the library maintainer so I don't think it's appropriate to change visibility in a documentation patch.

Occasionally private methods are useful for subclassing, so changing the inclusion of private or protected methods may hide relevant information.

If you wish to replace nodoc with real documentation that would be great, but it appears that these two methods are simply for utility.

Actions #4

Updated by drbrain (Eric Hodel) about 11 years ago

  • Status changed from Open to Closed
  • % Done changed from 0 to 100

This issue was solved with changeset r31527.
Pete, thank you for reporting this issue.
Your contribution to Ruby is greatly appreciated.
May Ruby be with you.

  • lib/set.rb (class Set): Add nodoc to internal-use methods. Patch by Pete Higgins. [Ruby 1.9 - Bug #4665]

Also available in: Atom PDF