[pypy-commit] cffi enum-as-int: Document

[arigo]

Author: Armin Rigo <arigo at tunes.org>
Branch: enum-as-int
Changeset: r1140:7ee599904f2f
Date: 2013-02-10 17:48 +0100
http://bitbucket.org/cffi/cffi/changeset/7ee599904f2f/

Log:	Document

diff --git a/doc/source/index.rst b/doc/source/index.rst
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1031,7 +1031,7 @@
 -------------------
 
 ``ffi.include(other_ffi)``: includes the typedefs, structs, unions and
-enums defined in another FFI instance.  Usage is similar to a
+enum types defined in another FFI instance.  Usage is similar to a
 ``#include`` in C, where a part of the program might include types
 defined in another part for its own usage.  Note that the include()
 method has no effect on functions, constants and global variables, which
@@ -1065,8 +1065,9 @@
   byte string or unicode string.  (Note that in some situation a single
   wchar_t may require a Python unicode string of length 2.)
 
-- If 'cdata' is an enum, returns the value of the enumerator as a
-  string, or ``#NUMBER`` if the value is out of range.
+- If 'cdata' is an enum, returns the value of the enumerator as a string.
+  If the value is out of range, it is simply returned as the stringified
+  integer.
 
 
 ``ffi.buffer(cdata, [size])``: return a buffer object that references
@@ -1254,8 +1255,8 @@
 |    C type     |   writing into         | reading from     |other operations|
 +===============+========================+==================+================+
 |   integers    | an integer or anything | a Python int or  | int()          |
-|               | on which int() works   | long, depending  |                |
-|               | (but not a float!).    | on the type      |                |
+|   and enums   | on which int() works   | long, depending  |                |
+|   `(*****)`   | (but not a float!).    | on the type      |                |
 |               | Must be within range.  |                  |                |
 +---------------+------------------------+------------------+----------------+
 |   ``char``    | a string of length 1   | a string of      | int()          |
@@ -1313,11 +1314,6 @@
 | union         | same as struct, but    |                  | read/write     |
 |               | with at most one field |                  | fields         |
 +---------------+------------------------+------------------+----------------+
-| enum          | an integer, or the enum| the enum value   | int()          |
-|               | value as a string or   | as a string, or  |                |
-|               | as ``"#NUMBER"``       | ``"#NUMBER"``    |                |
-|               |                        | if out of range  |                |
-+---------------+------------------------+------------------+----------------+
 
 .. versionchanged:: 0.3
    `(*)` Note that when calling a function, as per C, a ``item *`` argument
@@ -1349,6 +1345,14 @@
    without any precision loss, you need to define and use a family of C
    functions like ``long double add(long double a, long double b);``.
 
+.. versionchanged:: 0.6
+   `(*****)` Enums are now handled like ints.  In previous versions,
+   you would get the enum's value as a string.  Now we follow the C
+   convention and treat them as really equivalent to ints.  To compare
+   their value symbolically, use code like ``if x.field == lib.FOO``.
+   If you really want to get their value as a string, use
+   ``ffi.string(ffi.cast("the_enum_type", x.field))``.
+
 
 Reference: verifier
 -------------------