[New-bugs-announce] [issue5719] optparse: please provide a usage example in the module docstring

[Marius Gedminas]

New submission from Marius Gedminas <marius at gedmin.as>:

Please add a simple usage example to the module docstring in
optparse.py.  The example available in the Python library reference
would suffice (see http://python.org/doc/current/library/optparse.html).

Rationale: optparse is convenient, but a bit unintuitive.  As a single
data point, it took me a couple of years until I started remembering the
syntax without having to refer to the documentation (compare this with,
e.g. the csv module which you'll remember how to use after reading the
docs once).  Intuitively I always typed pydoc optparse in a terminal
window and was disappointed with the lack of examples.  The online docs
are good, but not as easy to reach as pydoc.

In my experience, it's quite often that when you reach for optparse
you're alreay shaving a yak (solving a problem needed to solve the real
problem), and the five extra mouse clicks needed to find optparse's docs
in the browser are rather disruptive.

----------
assignee: georg.brandl
components: Documentation
messages: 85722
nosy: georg.brandl, mgedmin
severity: normal
status: open
title: optparse: please provide a usage example in the module docstring

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue5719>
_______________________________________