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.
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.