Bug #4694: ERB::Compiler documentation

• Status: Closed
• Assignee: drbrain (Eric Hodel)
• Target version: -
• ruby -v: ruby 1.9.1p378

[thinkerbot (Simon Chiang)]

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

[drbrain (Eric Hodel)]

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

[mame (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 [e-mail]

[drbrain (Eric Hodel)]

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

[drbrain (Eric Hodel)]

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.