Add missing docstrings.

rhettinger · rhettinger · commit deb4da500b2a · 2004-03-14T07:54:37.000Z
diff --git a/Lib/StringIO.py b/Lib/StringIO.py
@@ -66,6 +66,12 @@ def __iter__(self):
         return self
 
     def next(self):
+        """A file object is its own iterator, for example iter(f) returns f
+        (unless f is closed). When a file is used as an iterator, typically
+        in a for loop (for example, for line in f: print line), the next()
+        method is called repeatedly. This method returns the next input line,
+        or raises StopIteration when EOF is hit.
+        """
         if self.closed:
             raise StopIteration
         r = self.readline()
@@ -81,10 +87,21 @@ def close(self):
             del self.buf, self.pos
 
     def isatty(self):
+        """Returns False because StringIO objects are not connected to a
+        tty-like device.
+        """
         _complain_ifclosed(self.closed)
         return False
 
     def seek(self, pos, mode = 0):
+        """Set the file's current position.
+
+        The mode argument is optional and defaults to 0 (absolute file
+        positioning); other values are 1 (seek relative to the current
+        position) and 2 (seek relative to the file's end).
+
+        There is no return value.
+        """
         _complain_ifclosed(self.closed)
         if self.buflist:
             self.buf += ''.join(self.buflist)
@@ -96,10 +113,18 @@ def seek(self, pos, mode = 0):
         self.pos = max(0, pos)
 
     def tell(self):
+        """Return the file's current position."""
         _complain_ifclosed(self.closed)
         return self.pos
 
     def read(self, n = -1):
+        """Read at most size bytes from the file
+        (less if the read hits EOF before obtaining size bytes).
+
+        If the size argument is negative or omitted, read all data until EOF
+        is reached. The bytes are returned as a string object. An empty
+        string is returned when EOF is encountered immediately.
+        """
         _complain_ifclosed(self.closed)
         if self.buflist:
             self.buf += ''.join(self.buflist)
@@ -113,6 +138,18 @@ def read(self, n = -1):
         return r
 
     def readline(self, length=None):
+        """Read one entire line from the file.
+
+        A trailing newline character is kept in the string (but may be absent
+        when a file ends with an incomplete line). If the size argument is
+        present and non-negative, it is a maximum byte count (including the
+        trailing newline) and an incomplete line may be returned.
+
+        An empty string is returned only when EOF is encountered immediately.
+
+        Note: Unlike stdio's fgets(), the returned string contains null
+        characters ('\0') if they occurred in the input.
+        """
         _complain_ifclosed(self.closed)
         if self.buflist:
             self.buf += ''.join(self.buflist)
@@ -130,6 +167,13 @@ def readline(self, length=None):
         return r
 
     def readlines(self, sizehint = 0):
+        """Read until EOF using readline() and return a list containing the
+        lines thus read.
+
+        If the optional sizehint argument is present, instead of reading up
+        to EOF, whole lines totalling approximately sizehint bytes (or more
+        to accommodate a final whole line).
+        """
         total = 0
         lines = []
         line = self.readline()
@@ -142,6 +186,16 @@ def readlines(self, sizehint = 0):
         return lines
 
     def truncate(self, size=None):
+        """Truncate the file's size.
+
+        If the optional size argument is present, the file is truncated to
+        (at most) that size. The size defaults to the current position.
+        The current file position is not changed unless the position
+        is beyond the new file size.
+
+        If the specified size exceeds the file's current size, the
+        file remains unchanged.
+        """
         _complain_ifclosed(self.closed)
         if size is None:
             size = self.pos
@@ -152,6 +206,10 @@ def truncate(self, size=None):
         self.buf = self.getvalue()[:size]
 
     def write(self, s):
+        """Write a string to the file.
+
+        There is no return value.
+        """
         _complain_ifclosed(self.closed)
         if not s: return
         # Force s to be a string or unicode
@@ -179,11 +237,20 @@ def write(self, s):
         self.pos = newpos
 
     def writelines(self, iterable):
+        """Write a sequence of strings to the file. The sequence can be any
+        iterable object producing strings, typically a list of strings. There
+        is no return value.
+
+        (The name is intended to match readlines(); writelines() does not add
+        line separators.)
+        """
         write = self.write
         for line in iterable:
             write(line)
 
     def flush(self):
+        """Flush the internal buffer
+        """
         _complain_ifclosed(self.closed)
 
     def getvalue(self):
