Bug #4694

ERB::Compiler documentation

Added by Simon Chiang almost 4 years ago. Updated almost 4 years ago.

[ruby-core:36185]
Status:Closed
Priority:Normal
Assignee:Eric Hodel
ruby -v:ruby 1.9.1p378 Backport:

Description

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

0001-added-documentation-for-ERB-Compiler.patch Magnifier (4.37 KB) Simon Chiang, 05/14/2011 02:32 PM

Associated revisions

Revision 31571
Added by Eric Hodel almost 4 years ago

  • lib/erb.rb: Document ERB::Compiler. Patch by Simon Chiang. [Ruby 1.9 - Bug #4694]

Revision 31571
Added by Eric Hodel almost 4 years ago

  • lib/erb.rb: Document ERB::Compiler. Patch by Simon Chiang. [Ruby 1.9 - Bug #4694]

Revision 31724
Added by Eric Hodel almost 4 years ago

  • lib/erb.rb: Hide documentation for implementation details of ERB. [Ruby 1.9 - Bug #4694]

Revision 31724
Added by Eric Hodel almost 4 years ago

  • lib/erb.rb: Hide documentation for implementation details of ERB. [Ruby 1.9 - Bug #4694]

Revision 31725
Added by Eric Hodel almost 4 years ago

  • lib/erb.rb: Restore documentation for ERB::Util and ERB::DefMethod (oops). [Ruby 1.9 - Bug #4694]

Revision 31725
Added by Eric Hodel almost 4 years ago

  • lib/erb.rb: Restore documentation for ERB::Util and ERB::DefMethod (oops). [Ruby 1.9 - Bug #4694]

History

#1 Updated by Eric Hodel almost 4 years ago

  • Status changed from Open to Closed
  • % Done changed from 0 to 100

This issue was solved with changeset r31571.
Simon, thank you for reporting this issue.
Your contribution to Ruby is greatly appreciated.
May Ruby be with you.


  • lib/erb.rb: Document ERB::Compiler. Patch by Simon Chiang. [Ruby 1.9 - Bug #4694]

#2 Updated by Yusuke Endoh almost 4 years ago

  • 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

#3 Updated by Eric Hodel almost 4 years ago

  • Status changed from Open to Closed

This issue was solved with changeset r31724.
Simon, thank you for reporting this issue.
Your contribution to Ruby is greatly appreciated.
May Ruby be with you.


  • lib/erb.rb: Hide documentation for implementation details of ERB. [Ruby 1.9 - Bug #4694]

#4 Updated by Eric Hodel almost 4 years ago

I have hidden ERB::Compiler from documentation.

I am not always sure which things should be documented for users and which for developers, in this case I made a mistake.

In other areas I'm not sure if the current lack of documentation (or :nodoc: markers) is because the API is intended to be private or because the API has not been documented yet. Of course, the ultimate choice is the maintainer's.

Thank you for reviewing my work, I can't get everything right by myself, ruby's library is too big for just one person to fully understand.

Also available in: Atom PDF