Bug #6997

Improve documentation for OptionParser

Added by Eike Dierks over 1 year ago. Updated over 1 year ago.

[ruby-core:47460]
Status:Closed
Priority:Normal
Assignee:Zachary Scott
Category:doc
Target version:2.0.0
ruby -v:ruby 1.9.3p194 (2012-04-20 revision 35410) [x86_64-darwin10] Backport:

Description

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 Magnifier (1.29 KB) Marcus Stollsteimer, 12/22/2012 07:51 PM

Associated revisions

Revision 38561
Added by Zachary Scott over 1 year ago

  • 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 [Bug #6997]

History

#1 Updated by Eike Dierks over 1 year 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.

#2 Updated by Zachary Scott over 1 year 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.

#3 Updated by Zachary Scott over 1 year ago

  • Category set to doc
  • Assignee set to Zachary Scott
  • Target version set to 2.0.0

#4 Updated by Usaku NAKAMURA over 1 year ago

  • Status changed from Open to Assigned

#5 Updated by Marcus Stollsteimer over 1 year ago

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

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

#6 Updated by Zachary Scott over 1 year 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 [Bug #6997]

#7 Updated by Zachary Scott over 1 year 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