Bug #4665

Add nodoc comments for Set methods

Added by Pete Higgins almost 3 years ago. Updated about 2 years ago.

[ruby-core:36093]
Status:Closed
Priority:Low
Assignee:Eric Hodel
Category:doc
Target version:-
ruby -v:1.9.2-p180 Backport:

Description

Set#flattenmerge and Set#dowith_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 Magnifier - Patch diff. (560 Bytes) Pete Higgins, 05/11/2011 11:38 AM

Associated revisions

Revision 31527
Added by Eric Hodel almost 3 years ago

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

History

#1 Updated by Loren Segal almost 3 years ago

I noticed that Set#dowithenum 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 #dowithenum.

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.

#2 Updated by Pete Higgins almost 3 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.

#3 Updated by Eric Hodel almost 3 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.

#4 Updated by Eric Hodel almost 3 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