https://redmine.ruby-lang.org/https://redmine.ruby-lang.org/favicon.ico?17113305112011-05-11T12:03:05ZRuby Issue Tracking SystemRuby master - Bug #4665: Add nodoc comments for Set methodshttps://redmine.ruby-lang.org/issues/4665?journal_id=168642011-05-11T12:03:05Zlsegal (Loren Segal)lsegal@soen.ca
<ul></ul><p>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 <a href="http://ruby-doc.org/stdlib/libdoc/set/rdoc/classes/Set.html" class="external">http://ruby-doc.org/stdlib/libdoc/set/rdoc/classes/Set.html</a> which seems to ignore private methods, including #do_with_enum.</p>
<p>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.</p>
<p>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.</p> Ruby master - Bug #4665: Add nodoc comments for Set methodshttps://redmine.ruby-lang.org/issues/4665?journal_id=168832011-05-12T07:44:06Zphiggins (Pete Higgins)pete@peterhiggins.org
<ul></ul><p>Hi Loren,</p>
<p>Rdoc excluding private methods in its output but considering them undocumented sounds like an issue with rdoc. I'll take that up with Eric.</p>
<p>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.</p> Ruby master - Bug #4665: Add nodoc comments for Set methodshttps://redmine.ruby-lang.org/issues/4665?journal_id=168882011-05-12T08:10:10Zdrbrain (Eric Hodel)drbrain@segment7.net
<ul></ul><p>By default, Ruby generates ri with --all so private methods will be picked up.</p>
<p>Method visibility is up to the library maintainer so I don't think it's appropriate to change visibility in a documentation patch.</p>
<p>Occasionally private methods are useful for subclassing, so changing the inclusion of private or protected methods may hide relevant information.</p>
<p>If you wish to replace nodoc with real documentation that would be great, but it appears that these two methods are simply for utility.</p> Ruby master - Bug #4665: Add nodoc comments for Set methodshttps://redmine.ruby-lang.org/issues/4665?journal_id=168922011-05-12T08:17:53Zdrbrain (Eric Hodel)drbrain@segment7.net
<ul><li><strong>Status</strong> changed from <i>Open</i> to <i>Closed</i></li><li><strong>% Done</strong> changed from <i>0</i> to <i>100</i></li></ul><p>This issue was solved with changeset r31527.<br>
Pete, thank you for reporting this issue.<br>
Your contribution to Ruby is greatly appreciated.<br>
May Ruby be with you.</p>
<hr>
<ul>
<li>lib/set.rb (class Set): Add nodoc to internal-use methods. Patch by Pete Higgins. [Ruby 1.9 - Bug <a class="issue tracker-1 status-5 priority-4 priority-default closed" title="Bug: Add nodoc comments for Set methods (Closed)" href="https://redmine.ruby-lang.org/issues/4665">#4665</a>]</li>
</ul>