Merged revisions 82262,82269,82434,82480-82481,82484-82485,82487-82488,82594,82599,82615 via svnmerge from

svn+ssh://svn.python.org/python/branches/py3k

................
  r82262 | georg.brandl | 2010-06-27 12:17:12 +0200 (So, 27 Jun 2010) | 1 line

  #9078: fix some Unicode C API descriptions, in comments and docs.
................
  r82269 | georg.brandl | 2010-06-27 12:59:19 +0200 (So, 27 Jun 2010) | 1 line

  Wording fix.
................
  r82434 | georg.brandl | 2010-07-02 09:41:51 +0200 (Fr, 02 Jul 2010) | 9 lines

  Merged revisions 82433 via svnmerge from
  svn+ssh://pythondev@svn.python.org/python/trunk

  ........
    r82433 | georg.brandl | 2010-07-02 09:33:50 +0200 (Fr, 02 Jul 2010) | 1 line

    Grammar and markup fixes.
  ........
................
  r82480 | georg.brandl | 2010-07-03 12:21:50 +0200 (Sa, 03 Jul 2010) | 1 line

  Wrap and use the correct directive.
................
  r82481 | georg.brandl | 2010-07-03 12:22:10 +0200 (Sa, 03 Jul 2010) | 1 line

  Use the right role.
................
  r82484 | georg.brandl | 2010-07-03 12:26:17 +0200 (Sa, 03 Jul 2010) | 9 lines

  Recorded merge of revisions 82474 via svnmerge from
  svn+ssh://pythondev@svn.python.org/python/trunk

  ........
    r82474 | georg.brandl | 2010-07-03 10:40:13 +0200 (Sa, 03 Jul 2010) | 1 line

    Fix role name.
  ........
................
  r82485 | georg.brandl | 2010-07-03 12:26:54 +0200 (Sa, 03 Jul 2010) | 9 lines

  Merged revisions 82483 via svnmerge from
  svn+ssh://pythondev@svn.python.org/python/trunk

  ........
    r82483 | georg.brandl | 2010-07-03 12:25:54 +0200 (Sa, 03 Jul 2010) | 1 line

    Add link to bytecode docs.
  ........
................
  r82487 | georg.brandl | 2010-07-03 12:33:26 +0200 (Sa, 03 Jul 2010) | 1 line

  Fix markup.
................
  r82488 | georg.brandl | 2010-07-03 12:41:33 +0200 (Sa, 03 Jul 2010) | 1 line

  Remove the need for a "()" empty argument list after opcodes.
................
  r82594 | georg.brandl | 2010-07-05 22:13:41 +0200 (Mo, 05 Jul 2010) | 1 line

  Update Vec class constructor, remove indirection via function, use operator module.
................
  r82599 | alexander.belopolsky | 2010-07-05 23:44:05 +0200 (Mo, 05 Jul 2010) | 1 line

  "Modernized" the demo a little.
................
  r82615 | georg.brandl | 2010-07-07 00:58:50 +0200 (Mi, 07 Jul 2010) | 1 line

  Fix typo.
................

9 files changed, 148 insertions, 121 deletions

diff --git a/Demo/classes/Vec.py b/Demo/classes/Vec.py
index edb3147..787af69 100755
--- a/Demo/classes/Vec.py
+++ b/Demo/classes/Vec.py
@@ -1,23 +1,41 @@
-# A simple vector class
+class Vec:
+    """ A simple vector class
 
+    Instances of the Vec class  can be constructed from numbers
 
-def vec(*v):
-    return Vec(*v)
+    >>> a = Vec(1, 2, 3)
+    >>> b = Vec(3, 2, 1)
 
+    added
+    >>> a + b
+    Vec(4, 4, 4)
 
-class Vec:
+    subtracted
+    >>> a - b
+    Vec(-2, 0, 2)
+
+    and multiplied by a scalar on the left
+    >>> 3.0 * a
+    Vec(3.0, 6.0, 9.0)
 
+    or on the right
+    >>> a * 3.0
+    Vec(3.0, 6.0, 9.0)
+    """
     def __init__(self, *v):
         self.v = list(v)
 
-    def fromlist(self, v):
+    @classmethod
+    def fromlist(cls, v):
         if not isinstance(v, list):
             raise TypeError
-        self.v = v[:]
-        return self
+        inst = cls()
+        inst.v = v
+        return inst
 
     def __repr__(self):
-        return 'vec(' + repr(self.v)[1:-1] + ')'
+        args = ', '.join(repr(x) for x in self.v)
+        return 'Vec({})'.format(args)
 
     def __len__(self):
         return len(self.v)
@@ -27,28 +45,24 @@ class Vec:
 
     def __add__(self, other):
         # Element-wise addition
-        v = list(map(lambda x, y: x+y, self, other))
-        return Vec().fromlist(v)
+        v = [x + y for x, y in zip(self.v, other.v)]
+        return Vec.fromlist(v)
 
     def __sub__(self, other):
         # Element-wise subtraction
-        v = list(map(lambda x, y: x-y, self, other))
-        return Vec().fromlist(v)
+        v = [x - y for x, y in zip(self.v, other.v)]
+        return Vec.fromlist(v)
 
     def __mul__(self, scalar):
         # Multiply by scalar
-        v = [x*scalar for x in self.v]
-        return Vec().fromlist(v)
+        v = [x * scalar for x in self.v]
+        return Vec.fromlist(v)
 
+    __rmul__ = __mul__
 
 
 def test():
-    a = vec(1, 2, 3)
-    b = vec(3, 2, 1)
-    print(a)
-    print(b)
-    print(a+b)
-    print(a-b)
-    print(a*3.0)
+    import doctest
+    doctest.testmod()
 
 test()
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index e8e0db8..32a7ca9 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -328,10 +328,10 @@ APIs:
    Coerce an encoded object *obj* to an Unicode object and return a reference with
    incremented refcount.
 
-   String and other char buffer compatible objects are decoded according to the
-   given encoding and using the error handling defined by errors.  Both can be
-   *NULL* to have the interface use the default values (see the next section for
-   details).
+   :class:`bytes`, :class:`bytearray` and other char buffer compatible objects
+   are decoded according to the given encoding and using the error handling
+   defined by errors. Both can be *NULL* to have the interface use the default
+   values (see the next section for details).
 
    All other objects, including Unicode objects, cause a :exc:`TypeError` to be
    set.
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index f1474cf..cc7b28e 100644
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -63,6 +63,9 @@ Glossary
       "intermediate language" is said to run on a :term:`virtual machine`
       that executes the machine code corresponding to each bytecode.
 
+      A list of bytecode instructions can be found in the documentation for
+      :ref:`the dis module <bytecodes>`.
+
    class
       A template for creating user-defined objects. Class definitions
       normally contain method definitions which operate on instances of the
diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
index e97743c..49b5673 100644
--- a/Doc/library/dis.rst
+++ b/Doc/library/dis.rst
@@ -17,6 +17,7 @@ and the interpreter.
    between versions of Python.  Use of this module should not be considered to
    work across Python VMs or Python releases.
 
+
 Example: Given the function :func:`myfunc`::
 
    def myfunc(alist):
@@ -37,23 +38,27 @@ The :mod:`dis` module defines the following functions and constants:
 
 .. function:: dis(x=None)
 
-   Disassemble the *x* object. *x* can denote either a module, a
-   class, a method, a function, or a code object.   For a module, it disassembles
-   all functions.  For a class, it disassembles all methods.  For a single code
-   sequence, it prints one line per bytecode instruction.  If no object is
-   provided, it disassembles the last traceback.
+   Disassemble the *x* object.  *x* can denote either a module, a
+   class, a method, a function, a code object, a string of source code or a
+   byte sequence of raw bytecode.  For a module, it disassembles all
+   functions.  For a class, it disassembles all methods.  For a code object
+   or sequence of raw bytecode, it prints one line per bytecode instruction.
+   Strings are first compiled to code objects with the :func:`compile`
+   built-in function before being disassembled.  If no object is provided,
+   this function disassembles the last traceback.
 
 
 .. function:: distb(tb=None)
 
-   Disassembles the top-of-stack function of a traceback, using the last traceback
-   if none was passed.  The instruction causing the exception is indicated.
+   Disassemble the top-of-stack function of a traceback, using the last
+   traceback if none was passed.  The instruction causing the exception is
+   indicated.
 
 
 .. function:: disassemble(code, lasti=-1)
               disco(code, lasti=-1)
 
-   Disassembles a code object, indicating the last instruction if *lasti* was
+   Disassemble a code object, indicating the last instruction if *lasti* was
    provided.  The output is divided in the following columns:
 
    #. the line number, for the first instruction of each line
@@ -139,225 +144,233 @@ Python Bytecode Instructions
 The Python compiler currently generates the following bytecode instructions.
 
 
-.. opcode:: STOP_CODE ()
+**General instructions**
+
+.. opcode:: STOP_CODE
 
    Indicates end-of-code to the compiler, not used by the interpreter.
 
 
-.. opcode:: NOP ()
+.. opcode:: NOP
 
    Do nothing code.  Used as a placeholder by the bytecode optimizer.
 
 
-.. opcode:: POP_TOP ()
+.. opcode:: POP_TOP
 
    Removes the top-of-stack (TOS) item.
 
 
-.. opcode:: ROT_TWO ()
+.. opcode:: ROT_TWO
 
    Swaps the two top-most stack items.
 
 
-.. opcode:: ROT_THREE ()
+.. opcode:: ROT_THREE
 
    Lifts second and third stack item one position up, moves top down to position
    three.
 
 
-.. opcode:: ROT_FOUR ()
+.. opcode:: ROT_FOUR
 
    Lifts second, third and forth stack item one position up, moves top down to
    position four.
 
 
-.. opcode:: DUP_TOP ()
+.. opcode:: DUP_TOP
 
    Duplicates the reference on top of the stack.
 
-Unary Operations take the top of the stack, apply the operation, and push the
-result back on the stack.
 
+**Unary operations**
 
-.. opcode:: UNARY_POSITIVE ()
+Unary operations take the top of the stack, apply the operation, and push the
+result back on the stack.
+
+.. opcode:: UNARY_POSITIVE
 
    Implements ``TOS = +TOS``.
 
 
-.. opcode:: UNARY_NEGATIVE ()
+.. opcode:: UNARY_NEGATIVE
 
    Implements ``TOS = -TOS``.
 
 
-.. opcode:: UNARY_NOT ()
+.. opcode:: UNARY_NOT
 
    Implements ``TOS = not TOS``.
 
 
-.. opcode:: UNARY_INVERT ()
+.. opcode:: UNARY_INVERT
 
    Implements ``TOS = ~TOS``.
 
 
-.. opcode:: GET_ITER ()
+.. opcode:: GET_ITER
 
    Implements ``TOS = iter(TOS)``.
 
+
+**Binary operations**
+
 Binary operations remove the top of the stack (TOS) and the second top-most
 stack item (TOS1) from the stack.  They perform the operation, and put the
 result back on the stack.
 
-
-.. opcode:: BINARY_POWER ()
+.. opcode:: BINARY_POWER
 
    Implements ``TOS = TOS1 ** TOS``.
 
 
-.. opcode:: BINARY_MULTIPLY ()
+.. opcode:: BINARY_MULTIPLY
 
    Implements ``TOS = TOS1 * TOS``.
 
 
-.. opcode:: BINARY_FLOOR_DIVIDE ()
+.. opcode:: BINARY_FLOOR_DIVIDE
 
    Implements ``TOS = TOS1 // TOS``.
 
 
-.. opcode:: BINARY_TRUE_DIVIDE ()
+.. opcode:: BINARY_TRUE_DIVIDE
 
    Implements ``TOS = TOS1 / TOS``.
 
 
-.. opcode:: BINARY_MODULO ()
+.. opcode:: BINARY_MODULO
 
    Implements ``TOS = TOS1 % TOS``.
 
 
-.. opcode:: BINARY_ADD ()
+.. opcode:: BINARY_ADD
 
    Implements ``TOS = TOS1 + TOS``.
 
 
-.. opcode:: BINARY_SUBTRACT ()
+.. opcode:: BINARY_SUBTRACT
 
    Implements ``TOS = TOS1 - TOS``.
 
 
-.. opcode:: BINARY_SUBSCR ()
+.. opcode:: BINARY_SUBSCR
 
    Implements ``TOS = TOS1[TOS]``.
 
 
-.. opcode:: BINARY_LSHIFT ()
+.. opcode:: BINARY_LSHIFT
 
    Implements ``TOS = TOS1 << TOS``.
 
 
-.. opcode:: BINARY_RSHIFT ()
+.. opcode:: BINARY_RSHIFT
 
    Implements ``TOS = TOS1 >> TOS``.
 
 
-.. opcode:: BINARY_AND ()
+.. opcode:: BINARY_AND
 
    Implements ``TOS = TOS1 & TOS``.
 
 
-.. opcode:: BINARY_XOR ()
+.. opcode:: BINARY_XOR
 
    Implements ``TOS = TOS1 ^ TOS``.
 
 
-.. opcode:: BINARY_OR ()
+.. opcode:: BINARY_OR
 
    Implements ``TOS = TOS1 | TOS``.
 
+
+**In-place operations**
+
 In-place operations are like binary operations, in that they remove TOS and
 TOS1, and push the result back on the stack, but the operation is done in-place
 when TOS1 supports it, and the resulting TOS may be (but does not have to be)
 the original TOS1.
 
-
-.. opcode:: INPLACE_POWER ()
+.. opcode:: INPLACE_POWER
 
    Implements in-place ``TOS = TOS1 ** TOS``.
 
 
-.. opcode:: INPLACE_MULTIPLY ()
+.. opcode:: INPLACE_MULTIPLY
 
    Implements in-place ``TOS = TOS1 * TOS``.
 
 
-.. opcode:: INPLACE_FLOOR_DIVIDE ()
+.. opcode:: INPLACE_FLOOR_DIVIDE
 
    Implements in-place ``TOS = TOS1 // TOS``.
 
 
-.. opcode:: INPLACE_TRUE_DIVIDE ()
+.. opcode:: INPLACE_TRUE_DIVIDE
 
    Implements in-place ``TOS = TOS1 / TOS``.
 
 
-.. opcode:: INPLACE_MODULO ()
+.. opcode:: INPLACE_MODULO
 
    Implements in-place ``TOS = TOS1 % TOS``.
 
 
-.. opcode:: INPLACE_ADD ()
+.. opcode:: INPLACE_ADD
 
    Implements in-place ``TOS = TOS1 + TOS``.
 
 
-.. opcode:: INPLACE_SUBTRACT ()
+.. opcode:: INPLACE_SUBTRACT
 
    Implements in-place ``TOS = TOS1 - TOS``.
 
 
-.. opcode:: INPLACE_LSHIFT ()
+.. opcode:: INPLACE_LSHIFT
 
    Implements in-place ``TOS = TOS1 << TOS``.
 
 
-.. opcode:: INPLACE_RSHIFT ()
+.. opcode:: INPLACE_RSHIFT
 
    Implements in-place ``TOS = TOS1 >> TOS``.
 
 
-.. opcode:: INPLACE_AND ()
+.. opcode:: INPLACE_AND
 
    Implements in-place ``TOS = TOS1 & TOS``.
 
 
-.. opcode:: INPLACE_XOR ()
+.. opcode:: INPLACE_XOR
 
    Implements in-place ``TOS = TOS1 ^ TOS``.
 
 
-.. opcode:: INPLACE_OR ()
+.. opcode:: INPLACE_OR
 
    Implements in-place ``TOS = TOS1 | TOS``.
 
 
-.. opcode:: STORE_SUBSCR ()
+.. opcode:: STORE_SUBSCR
 
    Implements ``TOS1[TOS] = TOS2``.
 
 
-.. opcode:: DELETE_SUBSCR ()
+.. opcode:: DELETE_SUBSCR
 
    Implements ``del TOS1[TOS]``.
 
-Miscellaneous opcodes.
 
+**Miscellaneous opcodes**
 
-.. opcode:: PRINT_EXPR ()
+.. opcode:: PRINT_EXPR
 
    Implements the expression statement for the interactive mode.  TOS is removed
    from the stack and printed.  In non-interactive mode, an expression statement is
    terminated with ``POP_STACK``.
 
 
-.. opcode:: BREAK_LOOP ()
+.. opcode:: BREAK_LOOP
 
    Terminates a loop due to a :keyword:`break` statement.
 
@@ -383,36 +396,35 @@ Miscellaneous opcodes.
    Calls ``dict.setitem(TOS1[-i], TOS, TOS1)``.  Used to implement dict
    comprehensions.
 
-
 For all of the SET_ADD, LIST_APPEND and MAP_ADD instructions, while the
 added value or key/value pair is popped off, the container object remains on
 the stack so that it is available for further iterations of the loop.
 
 
-.. opcode:: RETURN_VALUE ()
+.. opcode:: RETURN_VALUE
 
    Returns with TOS to the caller of the function.
 
 
-.. opcode:: YIELD_VALUE ()
+.. opcode:: YIELD_VALUE
 
    Pops ``TOS`` and yields it from a :term:`generator`.
 
 
-.. opcode:: IMPORT_STAR ()
+.. opcode:: IMPORT_STAR
 
    Loads all symbols not starting with ``'_'`` directly from the module TOS to the
    local namespace. The module is popped after loading all names. This opcode
    implements ``from module import *``.
 
 
-.. opcode:: POP_BLOCK ()
+.. opcode:: POP_BLOCK
 
    Removes one block from the block stack.  Per frame, there is a  stack of blocks,
    denoting nested loops, try statements, and such.
 
 
-.. opcode:: POP_EXCEPT ()
+.. opcode:: POP_EXCEPT
 
    Removes one block from the block stack. The popped block must be an exception
    handler block, as implicitly created when entering an except handler.
@@ -420,20 +432,20 @@ the stack so that it is available for further iterations of the loop.
    last three popped values are used to restore the exception state.
 
 
-.. opcode:: END_FINALLY ()
+.. opcode:: END_FINALLY
 
    Terminates a :keyword:`finally` clause.  The interpreter recalls whether the
    exception has to be re-raised, or whether the function returns, and continues
    with the outer-next block.
 
 
-.. opcode:: LOAD_BUILD_CLASS ()
+.. opcode:: LOAD_BUILD_CLASS
 
    Pushes :func:`builtins.__build_class__` onto the stack.  It is later called
    by ``CALL_FUNCTION`` to construct a class.
 
 
-.. opcode:: WITH_CLEANUP ()
+.. opcode:: WITH_CLEANUP
 
    Cleans up the stack when a :keyword:`with` statement block exits.  TOS is
    the context manager's :meth:`__exit__` bound method. Below TOS are 1--3
@@ -643,7 +655,7 @@ the more significant byte last.
    Pushes a try block from a try-except clause onto the block stack. *delta* points
    to the finally block.
 
-.. opcode:: STORE_MAP ()
+.. opcode:: STORE_MAP
 
    Store a key and value pair in a dictionary.  Pops the key and value while leaving
    the dictionary on the stack.
@@ -759,7 +771,7 @@ the more significant byte last.
    variable-arguments tuple, followed by explicit keyword and positional arguments.
 
 
-.. opcode:: HAVE_ARGUMENT ()
+.. opcode:: HAVE_ARGUMENT
 
    This is not really an opcode.  It identifies the dividing line between opcodes
    which don't take arguments ``< HAVE_ARGUMENT`` and those which do ``>=
diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst
index 5fdb543..1ca1620 100644
--- a/Doc/library/http.server.rst
+++ b/Doc/library/http.server.rst
@@ -284,30 +284,30 @@ of which this module provides three different variants:
       For example usage, see the implementation of the :func:`test` function
       invocation in the :mod:`http.server` module.
 
-The :class:`SimpleHTTPRequestHandler` class can be invoked the following manner
-with the :mod:`http.server` to create a very basic webserver serving files
-relative to the current directory.::
 
-        import http.server
-        import socketserver
+The :class:`SimpleHTTPRequestHandler` class can be used in the following
+manner in order to create a very basic webserver serving files relative to
+the current directory. ::
 
-        PORT = 8000
+   import http.server
+   import socketserver
 
-        Handler = http.server.SimpleHTTPRequestHandler
+   PORT = 8000
 
-        httpd = socketserver.TCPServer(("", PORT), Handler)
+   Handler = http.server.SimpleHTTPRequestHandler
 
-        print("serving at port", PORT)
-        httpd.serve_forever()
+   httpd = socketserver.TCPServer(("", PORT), Handler)
 
-:mod:`http.server` can also be invoked directly using the ``-m`` switch of
-interpreter a with ``port number`` argument which uses
-:class:`SimpleHTTPRequestHandler` as the default request Handler. Similar to
-the previous example, even this serves files relative to the current
-directory.::
+   print("serving at port", PORT)
+   httpd.serve_forever()
+
+:mod:`http.server` can also be invoked directly using the :option:`-m`
+switch of the interpreter a with ``port number`` argument.  Similar to
+the previous example, this serves files relative to the current directory. ::
 
         python -m http.server 8000
 
+
 .. class:: CGIHTTPRequestHandler(request, client_address, server)
 
    This class is used to serve either files or output of CGI scripts from the
diff --git a/Doc/tools/sphinxext/pyspecific.py b/Doc/tools/sphinxext/pyspecific.py
index 143003f..7111c06 100644
--- a/Doc/tools/sphinxext/pyspecific.py
+++ b/Doc/tools/sphinxext/pyspecific.py
@@ -5,7 +5,7 @@
 
     Sphinx extension with Python doc-specific markup.
 
-    :copyright: 2008, 2009 by Georg Brandl.
+    :copyright: 2008, 2009, 2010 by Georg Brandl.
     :license: Python license.
 """
 
@@ -149,7 +149,7 @@ import suspicious
 import re
 from sphinx import addnodes
 
-opcode_sig_re = re.compile(r'(\w+(?:\+\d)?)\s*\((.*)\)')
+opcode_sig_re = re.compile(r'(\w+(?:\+\d)?)(?:\s*\((.*)\))?')
 
 def parse_opcode_signature(env, sig, signode):
     """Transform an opcode signature into RST nodes."""
@@ -158,9 +158,10 @@ def parse_opcode_signature(env, sig, signode):
         raise ValueError
     opname, arglist = m.groups()
     signode += addnodes.desc_name(opname, opname)
-    paramlist = addnodes.desc_parameterlist()
-    signode += paramlist
-    paramlist += addnodes.desc_parameter(arglist, arglist)
+    if arglist is not None:
+        paramlist = addnodes.desc_parameterlist()
+        signode += paramlist
+        paramlist += addnodes.desc_parameter(arglist, arglist)
     return opname.strip()
 
 
diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst
index 8a2d645..bd88ad6 100644
--- a/Doc/tutorial/controlflow.rst
+++ b/Doc/tutorial/controlflow.rst
@@ -87,7 +87,6 @@ The :func:`range` Function
 If you do need to iterate over a sequence of numbers, the built-in function
 :func:`range` comes in handy.  It generates arithmetic progressions::
 
-
     >>> for i in range(5):
     ...     print(i)
     ...
@@ -97,9 +96,7 @@ If you do need to iterate over a sequence of numbers, the built-in function
     3
     4
 
-
-
-The given end point is never part of the generated list; ``range(10)`` generates
+The given end point is never part of the generated sequence; ``range(10)`` generates
 10 values, the legal indices for items of a sequence of length 10.  It
 is possible to let the range start at another number, or to specify a different
 increment (even negative; sometimes this is called the 'step')::
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index 0978770..3fe0c7a 100644
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -58,7 +58,7 @@ source.
 
 .. cmdoption:: -c <command>
 
-   Execute the Python code in *command*.  *command* can be one ore more
+   Execute the Python code in *command*.  *command* can be one or more
    statements separated by newlines, with significant leading whitespace as in
    normal module code.
 
diff --git a/Include/unicodeobject.h b/Include/unicodeobject.h
index cc2d535..7a3245a 100644
--- a/Include/unicodeobject.h
+++ b/Include/unicodeobject.h
@@ -496,14 +496,14 @@ PyAPI_FUNC(PyObject*) PyUnicode_FromUnicode(
     Py_ssize_t size             /* size of buffer */
     );
 
-/* Similar to PyUnicode_FromUnicode(), but u points to Latin-1 encoded bytes */
+/* Similar to PyUnicode_FromUnicode(), but u points to UTF-8 encoded bytes */
 PyAPI_FUNC(PyObject*) PyUnicode_FromStringAndSize(
     const char *u,        /* char buffer */
     Py_ssize_t size       /* size of buffer */
     );
 
 /* Similar to PyUnicode_FromUnicode(), but u points to null-terminated
-   Latin-1 encoded bytes */
+   UTF-8 encoded bytes */
 PyAPI_FUNC(PyObject*) PyUnicode_FromString(
     const char *u        /* string */
     );
@@ -548,7 +548,7 @@ PyAPI_FUNC(int) PyUnicode_Resize(
 
    Coercion is done in the following way:
 
-   1. String and other char buffer compatible objects are decoded
+   1. bytes, bytearray and other char buffer compatible objects are decoded
       under the assumptions that they contain data using the current
       default encoding. Decoding is done in "strict" mode.
 
@@ -572,7 +572,7 @@ PyAPI_FUNC(PyObject*) PyUnicode_FromEncodedObject(
    Unicode objects are passed back as-is (subclasses are converted to
    true Unicode objects), all other objects are delegated to
    PyUnicode_FromEncodedObject(obj, NULL, "strict") which results in
-   using the default encoding as basis for decoding the object.
+   using UTF-8 encoding as basis for decoding the object.
 
    The API returns NULL in case of an error. The caller is responsible
    for decref'ing the returned objects.
@@ -604,7 +604,7 @@ PyAPI_FUNC(void) _Py_ReleaseInternedUnicodeStrings(void);
 
 #ifdef HAVE_WCHAR_H
 
-/* Create a Unicode Object from the whcar_t buffer w of the given
+/* Create a Unicode Object from the wchar_t buffer w of the given
    size.
 
    The buffer is copied into the new object. */
@@ -663,7 +663,7 @@ PyAPI_FUNC(int) PyUnicode_ClearFreeList(void);
    parameters encoding and errors have the same semantics as the ones
    of the builtin unicode() API.
 
-   Setting encoding to NULL causes the default encoding to be used.
+   Setting encoding to NULL causes the default encoding (UTF-8) to be used.
 
    Error handling is set by errors which may also be set to NULL
    meaning to use the default handling defined for the codec. Default