[Python-Dev] RE: [Python-checkins] CVS: python/dist/src/Doc/lib libmmap.tex,NONE,1.1

[Mark Hammond]

> Documentation for the mmap module: proofreaders welcomed

OK :-)


> the file handle \var{fileno}, and returns a mmap object.  If you have
> a Python file object, its
> \method{fileno()} method returns the file's handle, which is
> just an integer.

This could be a little clearer - on first reading, I thought you were
talking about the return value.  Maybe something like: "if you wish to pass
an existing Python file object for this parameter, use its
\method{fileno()} method to obtain the fileno."


> \var{tagname}, if specified, is a string giving a tag name for
> the mapping. XXX what is the purpose of the tag name?

Something like: Windows allows you to have many different mappings against
the same file.  If you specify the name of an existing tag, that tag is
opened, otherwise a new tag of this name is created.  If this parameter is
None, the mapping is created without a name.  Avoiding the use of the tag
parameter will assist in keeping your code portable between Unix and
Windows.

> \begin{funcdesc}{mmap}{file, size \optional{, flags, prot}}
> (Unix version) Maps \var{length} bytes from the file specified by the
> file handle \var{fileno}, and returns a mmap object.  If you have a
> Python file object, its \method{fileno()} method returns the file's
> handle, which is just an integer.

I believe you mean the signature to say "fileno" instead of "file" - this
makes it consistent with the Windows signature, and reinforces that this
param is indeed identical.

As a meta-comment, the structure of this implies that the param signatures
are more different than they are - eg, it should be possible to write
portable mmap code in most cases, without concern for the platform.  the
platform only becomes relevant when you use the optional params for each
platform?


> \begin{methoddesc}{read}{\var{num}}
> Return a string containing up to \var{num} bytes taken from the

"taken from" -> "starting from" ??

> \begin{methoddesc}{write_byte}{\var{byte}}
> Write \var{byte} into memory at the current position of
> the file pointer; the file position is advanced by 1.
> \end{methoddesc}

The type of "byte" should be explained - its never clear to me if a "byte"
should be an int or a string of size 1.  In this case, it is the latter.

Looks good!

Mark.