Bug #4665: Add nodoc comments for Set methods

• Status: Closed
• Assignee: drbrain (Eric Hodel)
• Target version: -
• ruby -v: 1.9.2-p180

[phiggins (Pete Higgins)]

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.

[lsegal (Loren Segal)]

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.

[phiggins (Pete Higgins)]

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.

[drbrain (Eric Hodel)]

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.

[drbrain (Eric Hodel)]

• 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]