]> granicus.if.org Git - python/commitdiff
Issue #28496: Mark up constants 0, 1 and -1 that denote return values or
authorSerhiy Storchaka <storchaka@gmail.com>
Thu, 27 Oct 2016 18:41:04 +0000 (21:41 +0300)
committerSerhiy Storchaka <storchaka@gmail.com>
Thu, 27 Oct 2016 18:41:04 +0000 (21:41 +0300)
special input values as literal text.

13 files changed:
Doc/c-api/arg.rst
Doc/c-api/buffer.rst
Doc/c-api/capsule.rst
Doc/c-api/conversion.rst
Doc/c-api/file.rst
Doc/c-api/import.rst
Doc/c-api/init.rst
Doc/c-api/int.rst
Doc/c-api/marshal.rst
Doc/c-api/set.rst
Doc/c-api/slice.rst
Doc/c-api/structures.rst
Doc/c-api/unicode.rst

index 71e1fa3618871d29dded2e78366fe44c88ce7145..737568333c783629d118430d1488bafc2f40979d 100644 (file)
@@ -425,7 +425,7 @@ and the following format units are left untouched.
    only if its format string contains two or more format units.  If the format
    string is empty, it returns ``None``; if it contains exactly one format
    unit, it returns whatever object is described by that format unit.  To
-   force it to return a tuple of size 0 or one, parenthesize the format
+   force it to return a tuple of size ``0`` or one, parenthesize the format
    string.
 
    When memory buffers are passed as parameters to supply data to build
index e36d01f3da2c401a20d61145bf5c0a7d281fed5b..050db556cbfe888f2dcf044311575bba4c0b199b 100644 (file)
@@ -74,7 +74,7 @@ The new-style Py_buffer struct
    .. c:member:: int ndim
 
       The number of dimensions the memory represents as a multi-dimensional
-      array.  If it is 0, :c:data:`strides` and :c:data:`suboffsets` must be
+      array.  If it is ``0``, :c:data:`strides` and :c:data:`suboffsets` must be
       *NULL*.
 
    .. c:member:: Py_ssize_t *shape
@@ -143,7 +143,7 @@ Buffer related functions
 
 .. c:function:: int PyObject_CheckBuffer(PyObject *obj)
 
-   Return 1 if *obj* supports the buffer interface otherwise 0.
+   Return ``1`` if *obj* supports the buffer interface otherwise ``0``.
 
 
 .. c:function:: int PyObject_GetBuffer(PyObject *obj, Py_buffer *view, int flags)
@@ -164,7 +164,7 @@ Buffer related functions
       :c:data:`Py_buffer` structure is filled in with non-default values and/or
       raise an error if the object can't support a simpler view of its memory.
 
-      0 is returned on success and -1 on error.
+      ``0`` is returned on success and ``-1`` on error.
 
       The following table gives possible values to the *flags* arguments.
 
@@ -273,9 +273,9 @@ Buffer related functions
 
 .. c:function:: int PyBuffer_IsContiguous(Py_buffer *view, char fortran)
 
-   Return 1 if the memory defined by the *view* is C-style (*fortran* is
+   Return ``1`` if the memory defined by the *view* is C-style (*fortran* is
    ``'C'``) or Fortran-style (*fortran* is ``'F'``) contiguous or either one
-   (*fortran* is ``'A'``).  Return 0 otherwise.
+   (*fortran* is ``'A'``).  Return ``0`` otherwise.
 
 
 .. c:function:: void PyBuffer_FillContiguousStrides(int ndim, Py_ssize_t *shape, Py_ssize_t *strides, Py_ssize_t itemsize, char fortran)
@@ -289,7 +289,7 @@ Buffer related functions
 
    Fill in a buffer-info structure, *view*, correctly for an exporter that can
    only share a contiguous chunk of memory of "unsigned bytes" of the given
-   length.  Return 0 on success and -1 (with raising an error) on error.
+   length.  Return ``0`` on success and ``-1`` (with raising an error) on error.
 
 
 MemoryView objects
index 6f6250f671b5405ee45df645899ce3ecc83b2b78..b8642d0aba9248a8dafa07298c8b7cb6c08ba5be 100644 (file)
@@ -120,19 +120,19 @@ Refer to :ref:`using-capsules` for more information on using these objects.
    guaranteed to succeed.
 
    Return a nonzero value if the object is valid and matches the name passed in.
-   Return 0 otherwise.  This function will not fail.
+   Return ``0`` otherwise.  This function will not fail.
 
 .. c:function:: int PyCapsule_SetContext(PyObject *capsule, void *context)
 
    Set the context pointer inside *capsule* to *context*.
 
-   Return 0 on success.  Return nonzero and set an exception on failure.
+   Return ``0`` on success.  Return nonzero and set an exception on failure.
 
 .. c:function:: int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)
 
    Set the destructor inside *capsule* to *destructor*.
 
-   Return 0 on success.  Return nonzero and set an exception on failure.
+   Return ``0`` on success.  Return nonzero and set an exception on failure.
 
 .. c:function:: int PyCapsule_SetName(PyObject *capsule, const char *name)
 
@@ -140,11 +140,11 @@ Refer to :ref:`using-capsules` for more information on using these objects.
    outlive the capsule.  If the previous *name* stored in the capsule was not
    *NULL*, no attempt is made to free it.
 
-   Return 0 on success.  Return nonzero and set an exception on failure.
+   Return ``0`` on success.  Return nonzero and set an exception on failure.
 
 .. c:function:: int PyCapsule_SetPointer(PyObject *capsule, void *pointer)
 
    Set the void pointer inside *capsule* to *pointer*.  The pointer may not be
    *NULL*.
 
-   Return 0 on success.  Return nonzero and set an exception on failure.
+   Return ``0`` on success.  Return nonzero and set an exception on failure.
index b987469afbdff62bd2dcfd9ac558713e1831fef2..4b4d156e1a1b60946d270de672ec2b6ff19f60e4 100644 (file)
@@ -126,7 +126,7 @@ The following functions provide locale-independent string to number conversions.
 
    *format_code* must be one of ``'e'``, ``'E'``, ``'f'``, ``'F'``,
    ``'g'``, ``'G'`` or ``'r'``.  For ``'r'``, the supplied *precision*
-   must be 0 and is ignored.  The ``'r'`` format code specifies the
+   must be ``0`` and is ignored.  The ``'r'`` format code specifies the
    standard :func:`repr` format.
 
    *flags* can be zero or more of the values *Py_DTSF_SIGN*,
index bbd422368f9bd678d6eb533defc30c1017250d3c..e8bc6bf5a1e5c768c40521652dce70ae0446a1b7 100644 (file)
@@ -136,7 +136,7 @@ change in future releases of Python.
 
 .. c:function:: int PyFile_SetEncoding(PyFileObject *p, const char *enc)
 
-   Set the file's encoding for Unicode output to *enc*. Return 1 on success and 0
+   Set the file's encoding for Unicode output to *enc*. Return ``1`` on success and ``0``
    on failure.
 
    .. versionadded:: 2.3
@@ -145,7 +145,7 @@ change in future releases of Python.
 .. c:function:: int PyFile_SetEncodingAndErrors(PyFileObject *p, const char *enc, *errors)
 
    Set the file's encoding for Unicode output to *enc*, and its error
-   mode to *err*. Return 1 on success and 0 on failure.
+   mode to *err*. Return ``1`` on success and ``0`` on failure.
 
    .. versionadded:: 2.6
 
index 6f5678c931786a0f7c3e8b58f51c43feae1419c6..f0ea2277a958e73d137abcb68243c3150268f1b7 100644 (file)
@@ -66,7 +66,7 @@ Importing Modules
 
    .. versionchanged:: 2.6
       The function is an alias for :c:func:`PyImport_ImportModuleLevel` with
-      -1 as level, meaning relative import.
+      ``-1`` as level, meaning relative import.
 
 
 .. c:function:: PyObject* PyImport_ImportModuleLevel(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
index 6663551f1d91d28fbcfa0ad670109bf8d576c4b3..7643a3786c4b8310a0313dd498f401b16d50d61b 100644 (file)
@@ -43,8 +43,8 @@ Initializing and finalizing the interpreter
 
 .. c:function:: void Py_InitializeEx(int initsigs)
 
-   This function works like :c:func:`Py_Initialize` if *initsigs* is 1. If
-   *initsigs* is 0, it skips initialization registration of signal handlers, which
+   This function works like :c:func:`Py_Initialize` if *initsigs* is ``1``. If
+   *initsigs* is ``0``, it skips initialization registration of signal handlers, which
    might be useful when Python is embedded.
 
    .. versionadded:: 2.4
@@ -295,7 +295,7 @@ Process-wide parameters
 
    .. note::
       It is recommended that applications embedding the Python interpreter
-      for purposes other than executing a single script pass 0 as *updatepath*,
+      for purposes other than executing a single script pass ``0`` as *updatepath*,
       and update :data:`sys.path` themselves if desired.
       See `CVE-2008-5983 <https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983>`_.
 
@@ -307,13 +307,13 @@ Process-wide parameters
 
    .. versionadded:: 2.6.6
 
-   .. XXX impl. doesn't seem consistent in allowing 0/NULL for the params;
+   .. XXX impl. doesn't seem consistent in allowing ``0``/``NULL`` for the params;
       check w/ Guido.
 
 
 .. c:function:: void PySys_SetArgv(int argc, char **argv)
 
-   This function works like :c:func:`PySys_SetArgvEx` with *updatepath* set to 1.
+   This function works like :c:func:`PySys_SetArgvEx` with *updatepath* set to ``1``.
 
 
 .. c:function:: void Py_SetPythonHome(char *home)
@@ -917,8 +917,8 @@ pointer and a void pointer argument.
    .. index:: single: Py_AddPendingCall()
 
    Schedule a function to be called from the main interpreter thread.  On
-   success, 0 is returned and *func* is queued for being called in the
-   main thread.  On failure, -1 is returned without setting any exception.
+   success, ``0`` is returned and *func* is queued for being called in the
+   main thread.  On failure, ``-1`` is returned without setting any exception.
 
    When successfully queued, *func* will be *eventually* called from the
    main interpreter thread with the argument *arg*.  It will be called
@@ -929,7 +929,7 @@ pointer and a void pointer argument.
    * with the main thread holding the :term:`global interpreter lock`
      (*func* can therefore use the full C API).
 
-   *func* must return 0 on success, or -1 on failure with an exception
+   *func* must return ``0`` on success, or ``-1`` on failure with an exception
    set.  *func* won't be interrupted to perform another asynchronous
    notification recursively, but it can still be interrupted to switch
    threads if the global interpreter lock is released.
index 254219cc4efd0008c3465169469f350ae88e3a11..b2c5a448e32a2abd09ab3d83ea15c7fd78cb8059 100644 (file)
@@ -88,7 +88,7 @@ Plain Integer Objects
    Will first attempt to cast the object to a :c:type:`PyIntObject`, if it is not
    already one, and then return its value. If there is an error, ``-1`` is
    returned, and the caller should check ``PyErr_Occurred()`` to find out whether
-   there was an error, or whether the value just happened to be -1.
+   there was an error, or whether the value just happened to be ``-1``.
 
 
 .. c:function:: long PyInt_AS_LONG(PyObject *io)
index b82cc96b64acd9893a7d1b6810237a957c1dc51a..76120aefe1701f2c6401e072fbb7881c99cacffe 100644 (file)
@@ -13,8 +13,8 @@ binary mode.
 
 Numeric values are stored with the least significant byte first.
 
-The module supports two versions of the data format: version 0 is the
-historical version, version 1 (new in Python 2.4) shares interned strings in
+The module supports two versions of the data format: version ``0`` is the
+historical version, version ``1`` (new in Python 2.4) shares interned strings in
 the file, and upon unmarshalling.  Version 2 (new in Python 2.5) uses a binary
 format for floating point numbers.  *Py_MARSHAL_VERSION* indicates the current
 file format (currently 2).
index f6ebcf339227d13c233262fbc9c8c68e5e89b424..8bc1c8e6b8df919d64e421f1095dd1104d0e9606 100644 (file)
@@ -128,7 +128,7 @@ or :class:`frozenset` or instances of their subtypes.
 
 .. c:function:: int PySet_Contains(PyObject *anyset, PyObject *key)
 
-   Return 1 if found, 0 if not found, and -1 if an error is encountered.  Unlike
+   Return ``1`` if found, ``0`` if not found, and ``-1`` if an error is encountered.  Unlike
    the Python :meth:`__contains__` method, this function does not automatically
    convert unhashable sets into temporary frozensets.  Raise a :exc:`TypeError` if
    the *key* is unhashable. Raise :exc:`PyExc_SystemError` if *anyset* is not a
@@ -138,7 +138,7 @@ or :class:`frozenset` or instances of their subtypes.
 .. c:function:: int PySet_Add(PyObject *set, PyObject *key)
 
    Add *key* to a :class:`set` instance.  Does not apply to :class:`frozenset`
-   instances.  Return 0 on success or -1 on failure. Raise a :exc:`TypeError` if
+   instances.  Return ``0`` on success or ``-1`` on failure. Raise a :exc:`TypeError` if
    the *key* is unhashable. Raise a :exc:`MemoryError` if there is no room to grow.
    Raise a :exc:`SystemError` if *set* is not an instance of :class:`set` or its
    subtype.
@@ -154,7 +154,7 @@ subtypes but not for instances of :class:`frozenset` or its subtypes.
 
 .. c:function:: int PySet_Discard(PyObject *set, PyObject *key)
 
-   Return 1 if found and removed, 0 if not found (no action taken), and -1 if an
+   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:`~set.discard`
    method, this function does not automatically convert unhashable sets into
index f74230a9ec680e5ae020b01589ef6aa8c709310a..0de950ab12aaa661dbda843d6fea8073fb973b01 100644 (file)
@@ -34,9 +34,9 @@ Slice Objects
    assuming a sequence of length *length*. Treats indices greater than
    *length* as errors.
 
-   Returns 0 on success and -1 on error with no exception set (unless one of
+   Returns ``0`` on success and ``-1`` on error with no exception set (unless one of
    the indices was not :const:`None` and failed to be converted to an integer,
-   in which case -1 is returned with an exception set).
+   in which case ``-1`` is returned with an exception set).
 
    You probably do not want to use this function.  If you want to use slice
    objects in versions of Python prior to 2.3, you would probably do well to
@@ -57,7 +57,7 @@ Slice Objects
    of bounds indices are clipped in a manner consistent with the handling of
    normal slices.
 
-   Returns 0 on success and -1 on error with exception set.
+   Returns ``0`` on success and ``-1`` on error with exception set.
 
    .. versionadded:: 2.3
 
index 8833a36f7c1d57c2ac1176d1befe4288b670d7c3..fdee5f9fa0e17b3a955ef62debe1d0be86968beb 100644 (file)
@@ -314,7 +314,7 @@ definition with the same method name.
    handles use of the :keyword:`del` statement on that attribute more correctly
    than :c:macro:`T_OBJECT`.
 
-   :attr:`flags` can be 0 for write and read access or :c:macro:`READONLY` for
+   :attr:`flags` can be ``0`` for write and read access or :c:macro:`READONLY` for
    read-only access.  Using :c:macro:`T_STRING` for :attr:`type` implies
    :c:macro:`READONLY`.  Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX`
    members can be deleted.  (They are set to *NULL*).
index 7c056f4f91a73d3ee86a621c1c41a26e113bb9c0..4d1eaa1d778a0502525c506116859fafa4b8538d 100644 (file)
@@ -116,52 +116,52 @@ the Python configuration.
 
 .. c:function:: int Py_UNICODE_ISSPACE(Py_UNICODE ch)
 
-   Return 1 or 0 depending on whether *ch* is a whitespace character.
+   Return ``1`` or ``0`` depending on whether *ch* is a whitespace character.
 
 
 .. c:function:: int Py_UNICODE_ISLOWER(Py_UNICODE ch)
 
-   Return 1 or 0 depending on whether *ch* is a lowercase character.
+   Return ``1`` or ``0`` depending on whether *ch* is a lowercase character.
 
 
 .. c:function:: int Py_UNICODE_ISUPPER(Py_UNICODE ch)
 
-   Return 1 or 0 depending on whether *ch* is an uppercase character.
+   Return ``1`` or ``0`` depending on whether *ch* is an uppercase character.
 
 
 .. c:function:: int Py_UNICODE_ISTITLE(Py_UNICODE ch)
 
-   Return 1 or 0 depending on whether *ch* is a titlecase character.
+   Return ``1`` or ``0`` depending on whether *ch* is a titlecase character.
 
 
 .. c:function:: int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch)
 
-   Return 1 or 0 depending on whether *ch* is a linebreak character.
+   Return ``1`` or ``0`` depending on whether *ch* is a linebreak character.
 
 
 .. c:function:: int Py_UNICODE_ISDECIMAL(Py_UNICODE ch)
 
-   Return 1 or 0 depending on whether *ch* is a decimal character.
+   Return ``1`` or ``0`` depending on whether *ch* is a decimal character.
 
 
 .. c:function:: int Py_UNICODE_ISDIGIT(Py_UNICODE ch)
 
-   Return 1 or 0 depending on whether *ch* is a digit character.
+   Return ``1`` or ``0`` depending on whether *ch* is a digit character.
 
 
 .. c:function:: int Py_UNICODE_ISNUMERIC(Py_UNICODE ch)
 
-   Return 1 or 0 depending on whether *ch* is a numeric character.
+   Return ``1`` or ``0`` depending on whether *ch* is a numeric character.
 
 
 .. c:function:: int Py_UNICODE_ISALPHA(Py_UNICODE ch)
 
-   Return 1 or 0 depending on whether *ch* is an alphabetic character.
+   Return ``1`` or ``0`` depending on whether *ch* is an alphabetic character.
 
 
 .. c:function:: int Py_UNICODE_ISALNUM(Py_UNICODE ch)
 
-   Return 1 or 0 depending on whether *ch* is an alphanumeric character.
+   Return ``1`` or ``0`` depending on whether *ch* is an alphanumeric character.
 
 These APIs can be used for fast direct character conversions:
 
@@ -393,7 +393,7 @@ wchar_t Support
    Copy the Unicode object contents into the :c:type:`wchar_t` buffer *w*.  At most
    *size* :c:type:`wchar_t` characters are copied (excluding a possibly trailing
    0-termination character).  Return the number of :c:type:`wchar_t` characters
-   copied or -1 in case of an error.  Note that the resulting :c:type:`wchar_t`
+   copied or ``-1`` in case of an error.  Note that the resulting :c:type:`wchar_t`
    string may or may not be 0-terminated.  It is the responsibility of the caller
    to make sure that the :c:type:`wchar_t` string is 0-terminated in case this is
    required by the application. Also, note that the :c:type:`wchar_t*` string
@@ -1009,7 +1009,7 @@ They all return *NULL* or ``-1`` if an exception occurs.
 .. c:function:: PyObject* PyUnicode_Splitlines(PyObject *s, int keepend)
 
    Split a Unicode string at line breaks, returning a list of Unicode strings.
-   CRLF is considered to be one line break.  If *keepend* is 0, the Line break
+   CRLF is considered to be one line break.  If *keepend* is ``0``, the Line break
    characters are not included in the resulting strings.
 
 
@@ -1037,9 +1037,9 @@ They all return *NULL* or ``-1`` if an exception occurs.
 
 .. c:function:: Py_ssize_t PyUnicode_Tailmatch(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
 
-   Return 1 if *substr* matches ``str[start:end]`` at the given tail end
-   (*direction* == -1 means to do a prefix match, *direction* == 1 a suffix match),
-   0 otherwise. Return ``-1`` if an error occurred.
+   Return ``1`` if *substr* matches ``str[start:end]`` at the given tail end
+   (*direction* == ``-1`` means to do a prefix match, *direction* == ``1`` a suffix match),
+   ``0`` otherwise. Return ``-1`` if an error occurred.
 
    .. versionchanged:: 2.5
       This function used an :c:type:`int` type for *start* and *end*. This
@@ -1050,7 +1050,7 @@ They all return *NULL* or ``-1`` if an exception occurs.
 .. c:function:: Py_ssize_t PyUnicode_Find(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
 
    Return the first position of *substr* in ``str[start:end]`` using the given
-   *direction* (*direction* == 1 means to do a forward search, *direction* == -1 a
+   *direction* (*direction* == ``1`` means to do a forward search, *direction* == ``-1`` a
    backward search).  The return value is the index of the first match; a value of
    ``-1`` indicates that no match was found, and ``-2`` indicates that an error
    occurred and an exception has been set.
@@ -1075,7 +1075,7 @@ They all return *NULL* or ``-1`` if an exception occurs.
 .. c:function:: PyObject* PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)
 
    Replace at most *maxcount* occurrences of *substr* in *str* with *replstr* and
-   return the resulting Unicode object. *maxcount* == -1 means replace all
+   return the resulting Unicode object. *maxcount* == ``-1`` means replace all
    occurrences.
 
    .. versionchanged:: 2.5
@@ -1085,7 +1085,7 @@ They all return *NULL* or ``-1`` if an exception occurs.
 
 .. c:function:: int PyUnicode_Compare(PyObject *left, PyObject *right)
 
-   Compare two strings and return -1, 0, 1 for less than, equal, and greater than,
+   Compare two strings and return ``-1``, ``0``, ``1`` for less than, equal, and greater than,
    respectively.