[docs] Improve cross-references in C API (issue 19195)

[storchaka at gmail.com]

Reviewers: Georg,


http://bugs.python.org/review/19195/diff/9475/Doc/c-api/buffer.rst
File Doc/c-api/buffer.rst (right):

http://bugs.python.org/review/19195/diff/9475/Doc/c-api/buffer.rst#newcode47
Doc/c-api/buffer.rst:47: the buffer interface can be written to a file. 
While :meth:`~io.BufferedIOBase.write` only
On 2013/10/08 22:22:46, Georg wrote:
> just replace by ``write()``, two references in two sentences is not
needed

Perhaps :meth:`!write`? Or left as is? I suppose documentation formatter
can use special style decorations for different roles.

http://bugs.python.org/review/19195/diff/9475/Doc/c-api/typeobj.rst
File Doc/c-api/typeobj.rst (right):

http://bugs.python.org/review/19195/diff/9475/Doc/c-api/typeobj.rst#newcode643
Doc/c-api/typeobj.rst:643: When a type's :attr:`~object.__slots__`
declaration contains a slot named
On 2013/10/08 22:22:46, Georg wrote:
> here too: too many links are not needed and distract.

Doesn't many :c:member:`~PyTypeObject.tp_weaklistoffset` distract?



Please review this at http://bugs.python.org/review/19195/

Affected files:
  Doc/c-api/buffer.rst
  Doc/c-api/codec.rst
  Doc/c-api/file.rst
  Doc/c-api/object.rst
  Doc/c-api/set.rst
  Doc/c-api/typeobj.rst
  Doc/c-api/unicode.rst
  Doc/c-api/veryhigh.rst
  Doc/extending/building.rst
  Doc/extending/extending.rst
  Doc/extending/newtypes.rst


diff -r a49d313a28ae Doc/c-api/buffer.rst
--- a/Doc/c-api/buffer.rst	Tue Oct 08 21:08:48 2013 +0300
+++ b/Doc/c-api/buffer.rst	Tue Oct 08 22:54:20 2013 +0300
@@ -44,7 +44,7 @@
 
 An example consumer of the buffer interface is the :meth:`~io.BufferedIOBase.write`
 method of file objects: any object that can export a series of bytes through
-the buffer interface can be written to a file.  While :meth:`write` only
+the buffer interface can be written to a file.  While :meth:`~io.BufferedIOBase.write` only
 needs read-only access to the internal contents of the object passed to it,
 other methods such as :meth:`~io.BufferedIOBase.readinto` need write access
 to the contents of their argument.  The buffer interface allows objects to
diff -r a49d313a28ae Doc/c-api/codec.rst
--- a/Doc/c-api/codec.rst	Tue Oct 08 21:08:48 2013 +0300
+++ b/Doc/c-api/codec.rst	Tue Oct 08 22:54:20 2013 +0300
@@ -52,19 +52,19 @@
 
 .. c:function:: PyObject* PyCodec_IncrementalEncoder(const char *encoding, const char *errors)
 
-   Get an :class:`IncrementalEncoder` object for the given *encoding*.
+   Get an :class:`~codecs.IncrementalEncoder` object for the given *encoding*.
 
 .. c:function:: PyObject* PyCodec_IncrementalDecoder(const char *encoding, const char *errors)
 
-   Get an :class:`IncrementalDecoder` object for the given *encoding*.
+   Get an :class:`~codecs.IncrementalDecoder` object for the given *encoding*.
 
 .. c:function:: PyObject* PyCodec_StreamReader(const char *encoding, PyObject *stream, const char *errors)
 
-   Get a :class:`StreamReader` factory function for the given *encoding*.
+   Get a :class:`~codecs.StreamReader` factory function for the given *encoding*.
 
 .. c:function:: PyObject* PyCodec_StreamWriter(const char *encoding, PyObject *stream, const char *errors)
 
-   Get a :class:`StreamWriter` factory function for the given *encoding*.
+   Get a :class:`~codecs.StreamWriter` factory function for the given *encoding*.
 
 
 Registry API for Unicode encoding error handlers
diff -r a49d313a28ae Doc/c-api/file.rst
--- a/Doc/c-api/file.rst	Tue Oct 08 21:08:48 2013 +0300
+++ b/Doc/c-api/file.rst	Tue Oct 08 22:54:20 2013 +0300
@@ -40,7 +40,7 @@
 
    Return the file descriptor associated with *p* as an :c:type:`int`.  If the
    object is an integer, its value is returned.  If not, the
-   object's :meth:`fileno` method is called if it exists; the method must return
+   object's :meth:`~io.IOBase.fileno` method is called if it exists; the method must return
    an integer, which is returned as the file descriptor value.  Sets an
    exception and returns ``-1`` on failure.
 
@@ -50,7 +50,7 @@
    .. index:: single: EOFError (built-in exception)
 
    Equivalent to ``p.readline([n])``, this function reads one line from the
-   object *p*.  *p* may be a file object or any object with a :meth:`readline`
+   object *p*.  *p* may be a file object or any object with a :meth:`~io.IOBase.readline`
    method.  If *n* is ``0``, exactly one line is read, regardless of the length of
    the line.  If *n* is greater than ``0``, no more than *n* bytes will be read
    from the file; a partial line can be returned.  In both cases, an empty string
diff -r a49d313a28ae Doc/c-api/object.rst
--- a/Doc/c-api/object.rst	Tue Oct 08 21:08:48 2013 +0300
+++ b/Doc/c-api/object.rst	Tue Oct 08 22:54:20 2013 +0300
@@ -60,7 +60,7 @@
    Generic attribute getter function that is meant to be put into a type
    object's ``tp_getattro`` slot.  It looks for a descriptor in the dictionary
    of classes in the object's MRO as well as an attribute in the object's
-   :attr:`__dict__` (if present).  As outlined in :ref:`descriptors`, data
+   :attr:`~object.__dict__` (if present).  As outlined in :ref:`descriptors`, data
    descriptors take preference over instance attributes, while non-data
    descriptors don't.  Otherwise, an :exc:`AttributeError` is raised.
 
@@ -85,7 +85,7 @@
    object's ``tp_setattro`` slot.  It looks for a data descriptor in the
    dictionary of classes in the object's MRO, and if found it takes preference
    over setting the attribute in the instance dictionary. Otherwise, the
-   attribute is set in the object's :attr:`__dict__` (if present).  Otherwise,
+   attribute is set in the object's :attr:`~object.__dict__` (if present).  Otherwise,
    an :exc:`AttributeError` is raised and ``-1`` is returned.
 
 
@@ -189,7 +189,7 @@
    be done against every entry in *cls*. The result will be ``1`` when at least one
    of the checks returns ``1``, otherwise it will be ``0``. If *inst* is not a
    class instance and *cls* is neither a type object, nor a class object, nor a
-   tuple, *inst* must have a :attr:`__class__` attribute --- the class relationship
+   tuple, *inst* must have a :attr:`~instance.__class__` attribute --- the class relationship
    of the value of that attribute with *cls* will be used to determine the result
    of this function.
 
@@ -201,8 +201,8 @@
 either is not a class object, a more general mechanism is used to determine the
 class relationship of the two objects.  When testing if *B* is a subclass of
 *A*, if *A* is *B*, :c:func:`PyObject_IsSubclass` returns true.  If *A* and *B*
-are different objects, *B*'s :attr:`__bases__` attribute is searched in a
-depth-first fashion for *A* --- the presence of the :attr:`__bases__` attribute
+are different objects, *B*'s :attr:`~class.__bases__` attribute is searched in a
+depth-first fashion for *A* --- the presence of the :attr:`~class.__bases__` attribute
 is considered sufficient for this determination.
 
 
diff -r a49d313a28ae Doc/c-api/set.rst
--- a/Doc/c-api/set.rst	Tue Oct 08 21:08:48 2013 +0300
+++ b/Doc/c-api/set.rst	Tue Oct 08 22:54:20 2013 +0300
@@ -140,7 +140,7 @@
 
    Return 1 if found and removed, 0 if not found (no action taken), and -1 if an
    error is encountered.  Does not raise :exc:`KeyError` for missing keys.  Raise a
-   :exc:`TypeError` if the *key* is unhashable.  Unlike the Python :meth:`discard`
+   :exc:`TypeError` if the *key* is unhashable.  Unlike the Python :meth:`~set.discard`
    method, this function does not automatically convert unhashable sets into
    temporary frozensets. Raise :exc:`PyExc_SystemError` if *set* is an not an
    instance of :class:`set` or its subtype.
diff -r a49d313a28ae Doc/c-api/typeobj.rst
--- a/Doc/c-api/typeobj.rst	Tue Oct 08 21:08:48 2013 +0300
+++ b/Doc/c-api/typeobj.rst	Tue Oct 08 22:54:20 2013 +0300
@@ -510,7 +510,7 @@
 
    On the other hand, even if you know a member can never be part of a cycle, as a
    debugging aid you may want to visit it anyway just so the :mod:`gc` module's
-   :func:`get_referents` function will include it.
+   :func:`~gc.get_referents` function will include it.
 
    Note that :c:func:`Py_VISIT` requires the *visit* and *arg* parameters to
    :c:func:`local_traverse` to have these specific names; don't name them just
@@ -635,17 +635,17 @@
    reference list head than the base type.  Since the list head is always found via
    :c:member:`~PyTypeObject.tp_weaklistoffset`, this should not be a problem.
 
-   When a type defined by a class statement has no :attr:`__slots__` declaration,
+   When a type defined by a class statement has no :attr:`~object.__slots__` declaration,
    and none of its base types are weakly referenceable, the type is made weakly
    referenceable by adding a weak reference list head slot to the instance layout
    and setting the :c:member:`~PyTypeObject.tp_weaklistoffset` of that slot's offset.
 
-   When a type's :attr:`__slots__` declaration contains a slot named
+   When a type's :attr:`~object.__slots__` declaration contains a slot named
    :attr:`__weakref__`, that slot becomes the weak reference list head for
    instances of the type, and the slot's offset is stored in the type's
    :c:member:`~PyTypeObject.tp_weaklistoffset`.
 
-   When a type's :attr:`__slots__` declaration does not contain a slot named
+   When a type's :attr:`~object.__slots__` declaration does not contain a slot named
    :attr:`__weakref__`, the type inherits its :c:member:`~PyTypeObject.tp_weaklistoffset` from its
    base type.
 
@@ -825,15 +825,15 @@
    dictionary at a difference offset than the base type.  Since the dictionary is
    always found via :c:member:`~PyTypeObject.tp_dictoffset`, this should not be a problem.
 
-   When a type defined by a class statement has no :attr:`__slots__` declaration,
+   When a type defined by a class statement has no :attr:`~object.__slots__` declaration,
    and none of its base types has an instance variable dictionary, a dictionary
    slot is added to the instance layout and the :c:member:`~PyTypeObject.tp_dictoffset` is set to
    that slot's offset.
 
-   When a type defined by a class statement has a :attr:`__slots__` declaration,
+   When a type defined by a class statement has a :attr:`~object.__slots__` declaration,
    the type inherits its :c:member:`~PyTypeObject.tp_dictoffset` from its base type.
 
-   (Adding a slot named :attr:`__dict__` to the :attr:`__slots__` declaration does
+   (Adding a slot named :attr:`~object.__dict__` to the :attr:`~object.__slots__` declaration does
    not have the expected effect, it just causes confusion.  Maybe this should be
    added as a feature just like :attr:`__weakref__` though.)
 
diff -r a49d313a28ae Doc/c-api/unicode.rst
--- a/Doc/c-api/unicode.rst	Tue Oct 08 21:08:48 2013 +0300
+++ b/Doc/c-api/unicode.rst	Tue Oct 08 22:54:20 2013 +0300
@@ -978,7 +978,7 @@
 
    Create a Unicode object by decoding *size* bytes of the encoded string *s*.
    *encoding* and *errors* have the same meaning as the parameters of the same name
-   in the :func:`unicode` built-in function.  The codec to be used is looked up
+   in the :func:`str` built-in function.  The codec to be used is looked up
    using the Python codec registry.  Return *NULL* if an exception was raised by
    the codec.
 
@@ -988,7 +988,7 @@
 
    Encode a Unicode object and return the result as Python bytes object.
    *encoding* and *errors* have the same meaning as the parameters of the same
-   name in the Unicode :meth:`encode` method. The codec to be used is looked up
+   name in the Unicode :meth:`~str.encode` method. The codec to be used is looked up
    using the Python codec registry. Return *NULL* if an exception was raised by
    the codec.
 
@@ -998,7 +998,7 @@
 
    Encode the :c:type:`Py_UNICODE` buffer *s* of the given *size* and return a Python
    bytes object.  *encoding* and *errors* have the same meaning as the
-   parameters of the same name in the Unicode :meth:`encode` method.  The codec
+   parameters of the same name in the Unicode :meth:`~str.encode` method.  The codec
    to be used is looked up using the Python codec registry.  Return *NULL* if an
    exception was raised by the codec.
 
diff -r a49d313a28ae Doc/c-api/veryhigh.rst
--- a/Doc/c-api/veryhigh.rst	Tue Oct 08 21:08:48 2013 +0300
+++ b/Doc/c-api/veryhigh.rst	Tue Oct 08 22:54:20 2013 +0300
@@ -312,7 +312,7 @@
    frame *f* is executed, interpreting bytecode and executing calls as needed.
    The additional *throwflag* parameter can mostly be ignored - if true, then
    it causes an exception to immediately be thrown; this is used for the
-   :meth:`throw` methods of generator objects.
+   :meth:`~generator.throw` methods of generator objects.
 
 
 .. c:function:: int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)
diff -r a49d313a28ae Doc/extending/building.rst
--- a/Doc/extending/building.rst	Tue Oct 08 21:08:48 2013 +0300
+++ b/Doc/extending/building.rst	Tue Oct 08 22:54:20 2013 +0300
@@ -58,8 +58,9 @@
 It is common to pre-compute arguments to :func:`setup`, to better structure the
 driver script. In the example above, the\ ``ext_modules`` argument to
 :func:`setup` is a list of extension modules, each of which is an instance of
-the :class:`Extension`. In the example, the instance defines an extension named
-``demo`` which is build by compiling a single source file, :file:`demo.c`.
+the :class:`~distutils.extension.Extension`. In the example, the instance
+defines an extension named ``demo`` which is build by compiling a single source
+file, :file:`demo.c`.
 
 In many cases, building an extension is more complex, since additional
 preprocessor defines and libraries may be needed. This is demonstrated in the
diff -r a49d313a28ae Doc/extending/extending.rst
--- a/Doc/extending/extending.rst	Tue Oct 08 21:08:48 2013 +0300
+++ b/Doc/extending/extending.rst	Tue Oct 08 22:54:20 2013 +0300
@@ -860,9 +860,9 @@
 The cycle detector is able to detect garbage cycles and can reclaim them so long
 as there are no finalizers implemented in Python (:meth:`__del__` methods).
 When there are such finalizers, the detector exposes the cycles through the
-:mod:`gc` module (specifically, the
-``garbage`` variable in that module).  The :mod:`gc` module also exposes a way
-to run the detector (the :func:`collect` function), as well as configuration
+:mod:`gc` module (specifically, the :attr:`~gc.garbage` variable in that module).
+The :mod:`gc` module also exposes a way to run the detector (the
+:func:`~gc.collect` function), as well as configuration
 interfaces and the ability to disable the detector at runtime.  The cycle
 detector is considered an optional component; though it is included by default,
 it can be disabled at build time using the :option:`--without-cycle-gc` option
diff -r a49d313a28ae Doc/extending/newtypes.rst
--- a/Doc/extending/newtypes.rst	Tue Oct 08 21:08:48 2013 +0300
+++ b/Doc/extending/newtypes.rst	Tue Oct 08 22:54:20 2013 +0300
@@ -137,7 +137,7 @@
    If you want your type to be subclassable from Python, and your type has the same
    :c:member:`~PyTypeObject.tp_basicsize` as its base type, you may have problems with multiple
    inheritance.  A Python subclass of your type will have to list your type first
-   in its :attr:`__bases__`, or else it will not be able to call your type's
+   in its :attr:`~class.__bases__`, or else it will not be able to call your type's
    :meth:`__new__` method without getting an error.  You can avoid this problem by
    ensuring that your type has a larger value for :c:member:`~PyTypeObject.tp_basicsize` than its
    base type does.  Most of the time, this will be true anyway, because either your