Issue #4694 has been updated by Yusuke Endoh.

Status changed from Closed to Open

Hello,

Recent document patches are all outstanding work.
So I don't want to be a wet blanket, but I'm afraid if it is
not good that some of them (including this one) adds documents
to some private APIs.


I've considered that anything that have no rdoc is private.
So, I'm afraid if users mistake not-public APIs to be public
if they have documents.
Users should not use private APIs directly because they may
be modified, renamed, or even removed in future.

In this case, I believe that ERB::Compiler is not a public
API but just for internal.  :nodoc: was not a garnish, but
actually a document.


Is there a consensus that user cannot always use API even if
it has a rdoc?  If not, the rdoc should clearly state that it
may be private and that users are not expected to use them
directly.


Of course, writing a document for developers (such as a
technical notes like this) is also valuable work.  Please
use :stopdoc: or :nodoc: in the case.

Thanks,

-- 
Yusuke Endoh <mame / tsg.ne.jp>
----------------------------------------
Bug #4694: ERB::Compiler documentation
http://redmine.ruby-lang.org/issues/4694

Author: Simon Chiang
Status: Open
Priority: Normal
Assignee: Eric Hodel
Category: DOC
Target version: 
ruby -v: ruby 1.9.1p378


I added documentation for the ERB::Compiler and made sure the code works as of 1.9.1.


-- 
http://redmine.ruby-lang.org