Bug #6997: Improve documentation for OptionParser

• Status: Closed
• Assignee: zzak (zzak _)
• Target version: 2.0.0
• ruby -v: ruby 1.9.3p194 (2012-04-20 revision 35410) [x86_64-darwin10]

[eike.rb (Eike Dierks)]

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

[eike.rb (Eike Dierks)]

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.

[zzak (zzak _)]

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.

[zzak (zzak _)]

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

[usa (Usaku NAKAMURA)]

• Status changed from Open to Assigned

[stomar (Marcus Stollsteimer)]

• File rdoc_lib_optparse.patch rdoc_lib_optparse.patch added

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

@zzak (zzak _): 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.

[zzak (zzak _)]

• 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]

[zzak (zzak _)]

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.