Project

General

Profile

Actions

Bug #6997

closed

Improve documentation for OptionParser

Added by eike.rb (Eike Dierks) about 12 years ago. Updated almost 12 years ago.

Status:
Closed
Assignee:
Target version:
ruby -v:
ruby 1.9.3p194 (2012-04-20 revision 35410) [x86_64-darwin10]
Backport:
[ruby-core:47460]

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


Files

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) about 12 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 (zzak _) about 12 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 (zzak _) about 12 years ago

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

Updated by usa (Usaku NAKAMURA) almost 12 years ago

  • Status changed from Open to Assigned

Updated by stomar (Marcus Stollsteimer) almost 12 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 (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.

Actions #6

Updated by zzak (zzak _) almost 12 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 (zzak _) almost 12 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.

Actions

Also available in: Atom PDF

Like0
Like0Like0Like0Like0Like0Like0Like0