Ruby

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 http://ruby-doc.org/stdlib/libdoc/set/rdoc/classes/Set.html 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.

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.

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.