[Python-bugs-list] [ python-Bugs-797853 ] Small problems with the csv module's documentation

[SourceForge.net]

Bugs item #797853, was opened at 2003-08-30 13:07
Message generated for change (Settings changed) made by rhettinger
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=797853&group_id=5470

Category: Documentation
Group: Python 2.3
Status: Open
Resolution: None
Priority: 5
Submitted By: Florent Rougon (frougon)
>Assigned to: Skip Montanaro (montanaro)
Summary: Small problems with the csv module's documentation

Initial Comment:
The csv module's documentation in python 2.3 has the

following (not

severe) problems:



1. http://www.python.org/doc/current/lib/node545.html

    ("Modules Contents")



    In addition to the problems mentioned in bug #792558

    (csv.DictReader parms inconsistent with docs),

there is a

    repetition and a typo in the doc for csv.DictReader:



      If the row read has fewer fields than the

fieldnames sequence, the

      value of restval will be used as the default

value. [...] If the

      row read has fewer fields than the fieldnames

sequence, the

      remaining keys take the value of the optiona

restval parameter



    (the typo is "optiona")



2.

http://www.python.org/doc/current/lib/csv-fmt-params.html

    ("Dialects and Formatting Parameters")



    The first paragraph contains:



      In addition to, or instead of, the dialect

parameter, the

      programmer can also specify individual formatting

parameters,

      which have the same names as the attributes

defined above for the

      Dialect class.



    but the "attributes defined above" are actually

defined below. Also,

    the documentation of the "quoting" paramteres contains:



      It can take on any of the QUOTE_* constants

defined below and

      defaults to QUOTE_MINIMAL.



    which is probably correct for text, DVI, PS and PDF

output formats

    but a bit confusing in the HTML output (and perhaps

Info, for the

    systems where it is generated--at least in Debian)

since the

    "QUOTE_* constants" are defined in another HTML

page (the "Modules

    Contents" page). I think a real cross-reference

(\ref or whatever it

    is with the python doc. document class) should be

introduced.



3. http://www.python.org/doc/current/lib/node547.html

   ("Reader Objects")



   The first sentence reads:



     Reader objects (DictReader instances and objects

returned by the

     reader()function) have the following public methods:



   where a space is missing between "reader()" and

"function".



4. The docs are not ideally explicit as for what types

of parameters are

   accepted by some functions, for instance the "row"

and "rows"

   parameters of writer objects in

   http://www.python.org/doc/current/lib/node548.html

("Writer

   Objects").



Thank you very much for your work on Python!



----------------------------------------------------------------------

Comment By: Raymond Hettinger (rhettinger)
Date: 2003-08-31 00:46

Message:
Logged In: YES 
user_id=80475

Okay, fixed the first three.

Leaving the last one for Skip or Andrew.

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=797853&group_id=5470