Bug #6997


Improve documentation for OptionParser

Added by eike.rb (Eike Dierks) over 9 years ago. Updated over 9 years ago.

Target version:
ruby -v:
ruby 1.9.3p194 (2012-04-20 revision 35410) [x86_64-darwin10]


The documentation for OptionParser should be improved.

The current examples and and documentation do not yet describe
how to access non option args

I suggest to change the simple example in the doc as follows:

opts.banner = "Usage: example.rb [options] file ..."

p "files:" + ARGV

It should be stated explicitely in the description,
that parse! modifies the ARGV and removes all parseable args.

At least that is how I believe that the OptionParser.parse! works?
not yet tried it myself


rdoc_lib_optparse.patch (1.29 KB) rdoc_lib_optparse.patch stomar (Marcus Stollsteimer), 12/22/2012 07:51 PM

Updated by eike.rb (Eike Dierks) over 9 years ago

Ok, I was a bit blind on that,
I think that I now do understand how it works.

But anyway, the documentation should be improved.

I'd suggest to improve the examples to make it more clear upfront.

Updated by zzak (Zachary Scott) over 9 years ago

Better and more examples are always welcome, if you have any ideas
please feel free to submit a patch.

Otherwise, I'll try to put something together for this and #6996
sometime this week.

Updated by zzak (Zachary Scott) over 9 years ago

  • Category set to doc
  • Assignee set to zzak (Zachary Scott)
  • Target version set to 2.0.0

Updated by usa (Usaku NAKAMURA) over 9 years ago

  • Status changed from Open to Assigned

Updated by stomar (Marcus Stollsteimer) over 9 years ago

I tried to make this clearer, see patch.
I also changed the example to avoid a warning for "shadowed outer local variable".

@zzak (Zachary Scott): Do you think that the "Further documentation" section is of any use in the current form (since changeset r36960)? I would suggest to remove it completely, since filing a ticket for usage questions seems not the right thing to do.

Actions #6

Updated by zzak (Zachary Scott) over 9 years ago

  • Status changed from Assigned to Closed
  • % Done changed from 0 to 100

This issue was solved with changeset r38561.
Eike, thank you for reporting this issue.
Your contribution to Ruby is greatly appreciated.
May Ruby be with you.

  • lib/optparse.rb: Documentation for OptionParser to remove 'shadowed
    outer local variable' from example and make obvious ARGV with
    non-option arguments.
    Patch by Marcus Stollsteimer [ruby-core:47460] [Bug #6997]

Updated by zzak (Zachary Scott) over 9 years ago

Thanks Marcus, I was holding off on this until I got around to some other patches I have in mind for OptionParser, but you beat me to it :)

Re: remove further documentation: I think we should keep it, it doesn't hurt to mention the tracker if anyone comes across any bugs it will probably be documentation related when reading the optparse docs.


Also available in: Atom PDF