RDoc-style documentation for Ruby keywords

ruby-talk
1

Hi --

I've put together some RDoc-style documentation for the Ruby keywords.
It's at http://www.wobblini.net/keywords.

It's artificially presented in method-doc format, even though they're
not methods, because that helped me write it and see what it looked
like. I don't know what the best way to package and distribute it
properly is (obviously not as methods), and would be interested in
suggestions.

David

···

--
David A. Black / Ruby Power and Light, LLC
Ruby/Rails consulting & training: http://www.rubypal.com
Now available: The Well-Grounded Rubyist (http://manning.com/black2)
"Ruby 1.9: What You Need To Know" Envycasts with David A. Black
http://www.envycasts.com

2

David A. Black wrote:

Hi --

I've put together some RDoc-style documentation for the Ruby keywords.
It's at http://www.wobblini.net/keywords\.

It's artificially presented in method-doc format, even though they're
not methods, because that helped me write it and see what it looked
like. I don't know what the best way to package and distribute it
properly is (obviously not as methods), and would be interested in
suggestions.

Sweet.

It would be nice if this (or something like it) was part of the Ruby source such that generating the regular rdoc would emit this as well, and linked in some obvious way from the index.

In any event, I'd like to host this on ruby-doc.org.

···

--
James Britt

www.jamesbritt.com - Playing with Better Toys
www.ruby-doc.org - Ruby Help & Documentation
www.rubystuff.com - The Ruby Store for Ruby Stuff
www.neurogami.com - Smart application development

3

David A. Black wrote:

Hi --

I've put together some RDoc-style documentation for the Ruby keywords.
It's at http://www.wobblini.net/keywords\.

It's artificially presented in method-doc format, even though they're
not methods, because that helped me write it and see what it looked
like. I don't know what the best way to package and distribute it
properly is (obviously not as methods), and would be interested in
suggestions.

http://www.ruby-doc.org/docs/keywords/1.9/

···

--
James Britt

www.jamesbritt.com - Playing with Better Toys
www.ruby-doc.org - Ruby Help & Documentation
www.rubystuff.com - The Ruby Store for Ruby Stuff
www.neurogami.com - Smart application development

4

Not true that rescue "Must occur either inside a begin<code>/<code>end
block or a method definition (which implies begin)."

Counterexample:

puts "first line"
raise "oops" rescue puts "no problem"
puts "last line"

Or has this changed in 1.9? I focus on rescue because discovering this
single-expression version of rescue is not easy for beginners. m.

···

David A. Black <dblack@rubypal.com> wrote:

Hi --

I've put together some RDoc-style documentation for the Ruby keywords.
It's at http://www.wobblini.net/keywords\.

5

Using RDoc 2 will remove all the spurious links for common words like not, in, or, etc. (To force links, use #not, #in, #or, etc.)

···

On Jun 28, 2009, at 20:39, David A. Black wrote:

I've put together some RDoc-style documentation for the Ruby keywords.
It's at http://www.wobblini.net/keywords\.

It's artificially presented in method-doc format, even though they're
not methods, because that helped me write it and see what it looked
like. I don't know what the best way to package and distribute it
properly is (obviously not as methods), and would be interested in
suggestions.

6

Hi --

···

On Tue, 30 Jun 2009, Matt Neuburg wrote:

David A. Black <dblack@rubypal.com> wrote:

Hi --

I've put together some RDoc-style documentation for the Ruby keywords.
It's at http://www.wobblini.net/keywords\.

Not true that rescue "Must occur either inside a begin<code>/<code>end
block or a method definition (which implies begin)."

Counterexample:

puts "first line"
raise "oops" rescue puts "no problem"
puts "last line"

Or has this changed in 1.9? I focus on rescue because discovering this
single-expression version of rescue is not easy for beginners. m.

It's still there -- I'll add it. Thanks.

David

--
David A. Black / Ruby Power and Light, LLC
Ruby/Rails consulting & training: http://www.rubypal.com
Now available: The Well-Grounded Rubyist (http://manning.com/black2\)
"Ruby 1.9: What You Need To Know" Envycasts with David A. Black
http://www.envycasts.com

7

Hi --

···

On Tue, 30 Jun 2009, Eric Hodel wrote:

On Jun 28, 2009, at 20:39, David A. Black wrote:

I've put together some RDoc-style documentation for the Ruby keywords.
It's at http://www.wobblini.net/keywords\.

It's artificially presented in method-doc format, even though they're
not methods, because that helped me write it and see what it looked
like. I don't know what the best way to package and distribute it
properly is (obviously not as methods), and would be interested in
suggestions.

Using RDoc 2 will remove all the spurious links for common words like not, in, or, etc. (To force links, use #not, #in, #or, etc.)

Cool. Do you think there's a fundamentally better way to do the whole
thing than these phony method definitions? (def false, etc.) I like
having them split up, method-fashion, but it's a kluge.

David

--
David A. Black / Ruby Power and Light, LLC
Ruby/Rails consulting & training: http://www.rubypal.com
Now available: The Well-Grounded Rubyist (http://manning.com/black2\)
"Ruby 1.9: What You Need To Know" Envycasts with David A. Black
http://www.envycasts.com

8

Cool, thanks for the effort. But there is a typo on the main page:

1.9 keywords
Keywwords defined in 1.9.

"w" is a cool letter, but it can be overused ;).

Regards,
Florian

···

On Jun 29, 2009, at 7:43 PM, James Britt wrote:

RDoc Documentation

9

Since its related to 'rescue', I'll point out that you can also use 'else' to indicate code that only gets executed if none of the rescue clauses are (i.e., there is no exception). This is, of course, not like 'ensure' with is executed regardless.

This point should be added to 'else' even if it refers to the rescue and/or ensure docs (which don't mention this use of 'else' either).

-Rob

Rob Biedenharn http://agileconsultingllc.com
Rob@AgileConsultingLLC.com

···

On Jun 29, 2009, at 3:19 PM, David A. Black wrote:

Hi --

On Tue, 30 Jun 2009, Matt Neuburg wrote:

David A. Black <dblack@rubypal.com> wrote:

Hi --

I've put together some RDoc-style documentation for the Ruby keywords.
It's at http://www.wobblini.net/keywords\.

Not true that rescue "Must occur either inside a begin<code>/<code>end
block or a method definition (which implies begin)."

Counterexample:

puts "first line"
raise "oops" rescue puts "no problem"
puts "last line"

Or has this changed in 1.9? I focus on rescue because discovering this
single-expression version of rescue is not easy for beginners. m.

It's still there -- I'll add it. Thanks.

David

--
David A. Black / Ruby Power and Light, LLC
Ruby/Rails consulting & training: http://www.rubypal.com
Now available: The Well-Grounded Rubyist (http://manning.com/black2\)
"Ruby 1.9: What You Need To Know" Envycasts with David A. Black
http://www.envycasts.com

10

In RDoc 2 you can use directives to make methods:

···

On Jun 29, 2009, at 17:45, "David A. Black" <dblack@rubypal.com> wrote:

Cool. Do you think there's a fundamentally better way to do the whole
thing than these phony method definitions? (def false, etc.) I like
having them split up, method-fashion, but it's a kluge.

##
# :method: false
# blah blah comment

##
# :method: or
# etc.

But it still would need to live somewhere like Object (at least IIRC)

11

Hi --

···

On Wed, 1 Jul 2009, Florian Gilcher wrote:

On Jun 29, 2009, at 7:43 PM, James Britt wrote:

RDoc Documentation

Cool, thanks for the effort. But there is a typo on the main page:

1.9 keywords
Keywwords defined in 1.9.

"w" is a cool letter, but it can be overused ;).

That's what we call a "quadruple-u". It's a near-relation of the
famous sextuple-u you see in so many URLs :slight_smile:

David

--
David A. Black / Ruby Power and Light, LLC
Ruby/Rails consulting & training: http://www.rubypal.com
Now available: The Well-Grounded Rubyist (http://manning.com/black2\)
"Ruby 1.9: What You Need To Know" Envycasts with David A. Black
http://www.envycasts.com

12

Florian Gilcher wrote:

RDoc Documentation

Cool, thanks for the effort. But there is a typo on the main page:

1.9 keywords
Keywwords defined in 1.9.

"w" is a cool letter, but it can be overused ;).

Thwanks, I wwill fwix it.

···

On Jun 29, 2009, at 7:43 PM, James Britt wrote:

--
James Britt

www.jamesbritt.com - Playing with Better Toys
www.ruby-doc.org - Ruby Help & Documentation
www.rubystuff.com - The Ruby Store for Ruby Stuff
www.neurogami.com - Smart application development

13

Hi --

···

On Tue, 30 Jun 2009, Rob Biedenharn wrote:

Since its related to 'rescue', I'll point out that you can also use 'else' to indicate code that only gets executed if none of the rescue clauses are (i.e., there is no exception). This is, of course, not like 'ensure' with is executed regardless.

This point should be added to 'else' even if it refers to the rescue and/or ensure docs (which don't mention this use of 'else' either).

Very timely reminder -- I'm now going to go back and revise an answer
I gave someone here a couple of hours ago :slight_smile: (And I'll add it to the
document too.)

David

--
David A. Black / Ruby Power and Light, LLC
Ruby/Rails consulting & training: http://www.rubypal.com
Now available: The Well-Grounded Rubyist (http://manning.com/black2\)
"Ruby 1.9: What You Need To Know" Envycasts with David A. Black
http://www.envycasts.com

14

Really? This is the first I've heard of this, and it seems kind of
strange.

Maybe I'm misunderstanding the point of the 'else' clause, but
wouldn't you put code that "only gets executed if none of the rescue
clauses are (i.e., there is no exception)" in the main body of what
you're adding rescues to? (viz. begin block, method definition)

···

On Jun 29, 2:35 pm, Rob Biedenharn <R...@AgileConsultingLLC.com> wrote:

Since its related to 'rescue', I'll point out that you can also use
'else' to indicate code that only gets executed if none of the rescue
clauses are (i.e., there is no exception). This is, of course, not
like 'ensure' with is executed regardless.

--
-yossef

15

##
# :method: false
# blah blah comment

##
# :method: or
# etc.

Hmm. Could I request a full file example of how to use :method: ? The
following saved as an rb file doesn't seem to work...
=r

class Socket
module Tutorial
  # :method: test
  # test is an amazing method
end

···

##
# :method: false
# blah blah comment
end

class Array
# :method: tutorial
end
--
Posted via http://www.ruby-forum.com/\.

16

If there is something that isn't valid in the face of an exception and for which you do not want to catch any exceptions, but must occur prior to the ensure block.

begin
   a
   b
rescue => ex
   c
else
   d
ensure
   e
end

If doing d is only valid if b completes, and assuming that (x) means an exception happens during x, the possible sequences are:

(a),c,e
(a),(c),e
a,(b),c,e
a,(b),(c),e
a,b,d,e
a,b,(d),e

Note that d happens before e, but (d) does not cause the rescue clause to be invoked.

I know that I've run into the practical need for this at least once (but there were several rescue clauses, not just one). If I could recall the specific example, I'd have put it in.

-Rob

Rob Biedenharn http://agileconsultingllc.com
Rob@AgileConsultingLLC.com

···

On Jun 29, 2009, at 3:50 PM, Yossef Mendelssohn wrote:

On Jun 29, 2:35 pm, Rob Biedenharn <R...@AgileConsultingLLC.com> > wrote:

Since its related to 'rescue', I'll point out that you can also use
'else' to indicate code that only gets executed if none of the rescue
clauses are (i.e., there is no exception). This is, of course, not
like 'ensure' with is executed regardless.

Really? This is the first I've heard of this, and it seems kind of
strange.

Maybe I'm misunderstanding the point of the 'else' clause, but
wouldn't you put code that "only gets executed if none of the rescue
clauses are (i.e., there is no exception)" in the main body of what
you're adding rescues to? (viz. begin block, method definition)

--
-yossef

17

Yossef Mendelssohn wrote:

Since its related to 'rescue', I'll point out that you can also use
'else' to indicate code that only gets executed if none of the rescue
clauses are (i.e., there is no exception). This is, of course, not
like 'ensure' with is executed regardless.

Really? This is the first I've heard of this, and it seems kind of
strange.

Maybe I'm misunderstanding the point of the 'else' clause, but
wouldn't you put code that "only gets executed if none of the rescue
clauses are (i.e., there is no exception)" in the main body of what
you're adding rescues to? (viz. begin block, method definition)

Counterexample:

begin
  puts "According to your theory, this shouldn't be evaluated, "
  puts "but it will."
  raise RuntimeError
rescue
else
  puts "This, however, won't."
end

jwm

···

On Jun 29, 2:35 pm, Rob Biedenharn <R...@AgileConsultingLLC.com> > wrote:

18

Hi --

Yossef Mendelssohn wrote:

Since its related to 'rescue', I'll point out that you can also use
'else' to indicate code that only gets executed if none of the rescue
clauses are (i.e., there is no exception). This is, of course, not
like 'ensure' with is executed regardless.

Really? This is the first I've heard of this, and it seems kind of
strange.

Maybe I'm misunderstanding the point of the 'else' clause, but
wouldn't you put code that "only gets executed if none of the rescue
clauses are (i.e., there is no exception)" in the main body of what
you're adding rescues to? (viz. begin block, method definition)

Counterexample:

begin
puts "According to your theory, this shouldn't be evaluated, "
puts "but it will."
raise RuntimeError
rescue
else
puts "This, however, won't."
end

I think Yossef is talking about a case where something like this:

   begin
     require 'something'
   rescue LoadError
     puts "Sorry"
   else
     m = Something.new
   end

could be done like this instead:

   begin
     require 'something'
     m = Something.new
   rescue LoadError
     puts "Sorry"
   end

There's another thread going in which I've stumbled through several
iterations of advice to someone about exactly this problem, and
essentially ended up with that last one. A great example of
cross-thread heterodyning :slight_smile:

David

···

On Tue, 30 Jun 2009, Jörg W Mittag wrote:

On Jun 29, 2:35 pm, Rob Biedenharn <R...@AgileConsultingLLC.com> >> wrote:

--
David A. Black / Ruby Power and Light, LLC
Ruby/Rails consulting & training: http://www.rubypal.com
Now available: The Well-Grounded Rubyist (http://manning.com/black2\)
"Ruby 1.9: What You Need To Know" Envycasts with David A. Black
http://www.envycasts.com

19

I could have explained that better. I was thinking more along the
lines of

    begin
      puts "This will be executed, "
      puts "as will this."
      raise
      puts "This, however, won't."
    rescue
    else
      put "And neither will this."
    end

Rob's a-e example points out the benefit of using the else clause, but
it's still strange and slippery to me. I've never run into a practical
need for it, though I'm not inclined to disbelieve him when he says he
has. It would be great to see a concrete example.

···

On Jun 29, 3:35 pm, Jörg W Mittag <JoergWMittag+Use...@GoogleMail.Com> wrote:

Yossef Mendelssohn wrote:
> Maybe I'm misunderstanding the point of the 'else' clause, but
> wouldn't you put code that "only gets executed if none of the rescue
> clauses are (i.e., there is no exception)" in the main body of what
> you're adding rescues to? (viz. begin block, method definition)

Counterexample:

begin
puts "According to your theory, this shouldn't be evaluated, "
puts "but it will."
raise RuntimeError
rescue
else
puts "This, however, won't."
end

--
-yossef

20

I think Yossef is talking about a case where something like this:

begin
require 'something'
rescue LoadError
puts "Sorry"
else
m = Something.new
end

could be done like this instead:

begin
require 'something'
m = Something.new
rescue LoadError
puts "Sorry"
end

Basically, yes.

There's another thread going in which I've stumbled through several
iterations of advice to someone about exactly this problem, and
essentially ended up with that last one. A great example of
cross-thread heterodyning :slight_smile:

I saw that. One thing that could be said about the

    begin
      require 'something'
    rescue LoadError
      puts "Sorry"
    else
      m = Something.new
    end

example is that it gets the exception out of the way quickly and then
you can easily see the body of code that matters. That order makes it
clear that the begin/rescue is only to safely wrap the optional code
that would execute if you only had the right library present (or gem
installed).

On the other hand, structuring it as

    begin
      require 'something'
      m = Something.new
    rescue LoadError
      puts "Sorry"
    end

would leave you hanging if the optional code is substantial. You could
have to look down a bit before realizing why the begin block was even
there.

···

On Jun 29, 3:43 pm, "David A. Black" <dbl...@rubypal.com> wrote:

--
-yossef