Where is the documentation for Ruby OptionParser's parse! method?

Question

I have been unable to locate any documentation for parse!, a very commonly used instance method for the OptionParser class from Ruby's standard distribution.

I have seen parse! used in the examples at the top of the documentation for the OptionParse class. However, I am looking for documentation specific to this method, documentation that describes what exactly the method does. For example, the documentation should, among other things, give a clue as to why the method name ends in a bang (presumably this method removes the options from ARGV). It might also describe whether I should expect anything useful to be returned from parse! (number of options parsed?).

I have tried reading the official documentation for the OptionParse class and for all of the subclasses listed at the top of that class. I also consulted the relevant section Programming Ruby (the "pickaxe book").

I am not asking what parse! does; I have a decent (if imperfect) sense of it from reading other StackOverlow threads. I am looking to improve my ability to make sense of Ruby documentation. I am more accustomed to Perl/CPAN documentation. When I am dealing with Ruby documentaiton, even for standard distribution modules, I feel very lost. It's as though someone has deleted or relocated key bits of information. Sometimes I come across a location where I think the documentation for a key method would be, and find I am left to simply examine the source code for said method. I wonder if perhaps I am just not used to how information is organized in Ruby. Maybe this can be a good lesson for me.

Your question is not exactly clear. Do you want to know about `OptionParser.parse!` or how to make sense of Ruby docs? — the Tin Man, Aug 14 '11 at 20:55
I was looking for an URL to the documentation for Ruby OptionParser's parse! method. The question is in the title: "Where is the documentation for Ruby OptionParser's parse! method?" It was not on ruby-doc.org, for some reason, but the rubydoc.info link you provided does contain a much fuller list of methods, which is very helpful. — Ryan Tate, Aug 17 '11 at 18:27

the Tin Man · Accepted Answer · 2011-08-18T22:52:41.577

I use Rubydoc.info for most of my documentation. The docs for OptParse explain parse pretty clearly I thought:

Parses command line arguments argv in order when environment variable POSIXLY_CORRECT is set, and in permutation mode otherwise.

If you check the source link for that method you'll see it's implemented using parse!:

def parse(*argv)
  argv = argv[0].dup if argv.size == 1 and Array === argv[0]
  parse!(argv)
end

And looking at parse! will tell you even more.

Regarding missing or deleted pieces of information: Most Ruby docs are generated by RDoc, or YARD, based on what is in the source code so, missing information is usually the fault of the author of the code.

Some people are too busy to document correctly, either ignoring it entirely, or not knowing what to document. We, as users of the code, can help though by submitting changes to the source that implements better documentation. I've done it many times on different projects, when I found something confusing or wrong.

I added a direct link to the parse method documentation; you had linked only to the very top of a frameset containing all OptParse classes and their methods. I'll go ahead and accept the answer with those changes. The direct URL is: http://rubydoc.info/stdlib/optparse/1.9.2/OptionParser#parse-instance_method — Ryan Tate, Aug 17 '11 at 18:23

Where is the documentation for Ruby OptionParser's parse! method?

1 Answers1