1) I don't know how coerce works.
http://blog.rubybestpractices.com/posts/rklemme/019-Complete_Numeric_Class.html
When I read this and the response form Adam:
You are free to improve the documentation and open a ticket on redmine
assigned to Eric Hodel.
it reminds me what I just wrote a few weeks ago, no real feedback at
all: Ruby Readline - and why ruby can learn from python - Ruby - Ruby-Forum .
Since you posted it to ruby-talk and not to ruby-core (or a ticket) I missed it. In brief, if you think it can be better, file a ticket.
The reason I say "file a ticket" is because I will forget if we only talk about it here. I'm very busy with both work and preparing for the Ruby 1.9.3 release so I probably won't have free time available to work on these things for a while now.
From your post:
Well, the problem as I see it is that tutorial-like examples, when you
have quite some of them, don't really fit well within a discrete method
documentation. It makes it hard for the developer to discover. IMHO all
the examples from Readline.readline and what I've added should be moved
out either into the README or into the Readline module description and
the actual method documentations should be made more slim. But who to
make a call for anything here?
If you think the organization of something is poor then file a ticket proposing a reorganization. I agree that it's easier to read when some examples are moved up to the top level.
Take a look at the documentation of Net::HTTP or OpenSSL in Ruby 1.9.3-preview1. They've been reorganized and improved to show you the various ways you can use the two libraries in one place with slimmer documentation on individual methods. I think this is a vast improvement over hunting through the 10 or 15 methods you may need to call to get a working program, and I think Readline would benefit from a similar reorganization.
When I generate the docs from it, it looks like this
http://i.imgur.com/e7U5G.png . Ugh. The headings don't suit well and the
source code has no highlighting (in case your wonder: that's FF 5 with
150% full-page zoom).
If you think the RDoc HTML output can be better then file a ticket or write a new template or generator. The current default generator, Darfkish, was contributed by Michael Granger. HTML and web browsers have advanced quite a bit since it was included so if something nicer is built it can be added to RDoc and be made the default.
If it were me, I'd bow before Robert for doing this great work, ask for
his permission and simply stuff all his wisdom into the docs and let the
world joy on it.
Done!
My problem with that approach and this here
http://blog.segment7.net/2011/05/09/ruby-1-9-3-documentation-challenge
http://blog.steveklabnik.com/2011/05/10/contributing-to-ruby-s-documentation.html
is the following: Roberts post includes a and much more widened example
and I'd be all for including it, but it doesn't fit will with how rdocs
are most commonly used currently, that is, one page for all methods. If
documentation for methods becomes to long as I outlined, things get
noticeably unreadable.
I've no further solution, but somehow it strikes me that the whole ruby
documentation misses the next evolutionary step, away from the docs only
generated from the sources to a) possible include much more meta
documentation (manuals, tutorials, etc.) and b) provide *a*/*the*
*official* ruby docs, not just class based docs, but also including
introductory articles etc., e.g. from the existing ruby wikibook and so
on, allowing comments on the docs as others mentioned and what not features.
Ruby still needs more of two types of documentation, the manuals, tutorials, etc. and the class and method-level documentation of the standard library. Through the efforts of my documentation challenge the latter has grown to having ⅔ of the standard library documented for Ruby 1.9.3 out of about 15,000 items. I don't know of anybody addressing the former beyond these recent discussion and what's present at ruby-doc.org.
But unfortunately it's lacking a power behind, a group of volunteers a)
providing the technical environment and b) writers. When I look at other
projects, e.g. PHP, the doc team not only provides infrastructure and
assistance, they're also permanently communicating with the core
developers to properly document new things for a release, properly
describe backward compatibility problems (I mean, just look at the list
at http://www.php.net/manual/en/ ).
I became a Ruby committer through submitting documentation patches, and anyone can become a committer the same way. I did a decent job of committing documentation patches in a timely manner, but it would be great if I could have some extra help. I don't see any reason why people couldn't be both.
I wish I'd the skills for either forming a basis or writing good docs,
unfortunately I'm quite un-gifted for the latter (I still try to improve
it and contribute) and I seriously lack ruby-foo or whatnot for the former.
For the documentation challenge, writing good documentation was most-preferred, but I applied even "poor" documentation patches after appropriate editing or expansion. For every patch I wasn't able to directly apply I provided feedback to the submitter. In total, I think only two patches weren't applied out of between 40 and 50, one that duplicated an earlier submission and one being a mistaken typo fix about the math meaning of a number range like "[0, 1)".
For class and method-level documentation even poor documentation can be edited or expanded into something good! Through feedback even you can write good documentation! Please do not be afraid of rejection, I try very hard to avoid rejecting documentation patches.
···
On Aug 2, 2011, at 7:30 AM, Markus Fischer wrote:
On 02.08.2011 14:55, Robert Klemme wrote:
On Tue, Aug 2, 2011 at 12:40 PM, 7stud -- <bbxx789_05ss@yahoo.com> wrote:
On 02.08.2011 12:32, Adam Prescott wrote:
On 02.08.2011 13:26, Adam Prescott wrote:
