wip

baylej · Feb 13, 2019 · 059d9ab · 059d9ab
1 parent 68dbcef
commit 059d9ab
Show file tree

Hide file tree

Showing 5 changed files with 94 additions and 13 deletions.
diff --git a/README.md b/README.md
@@ -43,4 +43,4 @@ See the dumper example (`examples/dumper/dumper.c`) for an in-depth usage of TMX
 
 ### Help
 
-See the [Wiki](https://github.com/baylej/tmx/wiki/).
+See the [Documentation](http://libtmx.rtfd.io/).
diff --git a/doc/src/build.rst b/doc/src/build.rst
@@ -1,6 +1,10 @@
 Building libTMX
 ===============
 
+.. warning::
+   As **libTMX** has an ever-changing API (and ABI) therefore the recommended way to use it is to directly incorporate
+   it in the sources of your project.
+
 Prerequisites
 -------------
 

diff --git a/doc/src/error.rst b/doc/src/error.rst
@@ -0,0 +1,87 @@
+Error Handling
+==============
+
+.. warning::
+   Error management is the only non thread-safe functionality in **libTMX**, due to the *tmx_errno* global it is based on.
+
+Error detection
+---------------
+
+.. c:var:: tmx_error_codes tmx_errno
+
+   Every time a load function fails (map load functions would return NULL, resource load functions would return 0) this
+   global is set to an error code.
+
+Error codes
+-----------
+
+.. c:type:: enum tmx_error_codes
+
+   Possible values for :c:data:`tmx_errno`.
+
+   +------------+---------------------------------------------------------------------------------------------+
+   | Error code | Description                                                                                 |
+   +============+=============================================================================================+
+   | E_NONE     | No error so far.                                                                            |
+   +------------+---------------------------------------------------------------------------------------------+
+   | E_UNKN     | Unknown error, call :c:func:`tmx_strerr` to get a description of the error.                 |
+   +------------+---------------------------------------------------------------------------------------------+
+   | E_INVAL    | Invalid argument, example: you passed NULL to :c:func:`tmx_load`.                           |
+   +------------+---------------------------------------------------------------------------------------------+
+   | E_ALLOC    | Memory allocation failed (running out of memory).                                           |
+   +------------+---------------------------------------------------------------------------------------------+
+   | E_ACCESS   | Missing privileges to access the file.                                                      |
+   +------------+---------------------------------------------------------------------------------------------+
+   | E_NOENT    | File not found.                                                                             |
+   +------------+---------------------------------------------------------------------------------------------+
+   | E_FORMAT   | Unsupported/Unknown file format (libTMX only supports the TMX/XML format).                  |
+   +------------+---------------------------------------------------------------------------------------------+
+   | E_ENCCMP   | Unsupported/Unknown data encoding/compression (libTMX only supports gzip and base64).       |
+   +------------+---------------------------------------------------------------------------------------------+
+   | E_FONCT    | Feature not enabled (ZLib not enabled when libTMX was built).                               |
+   +------------+---------------------------------------------------------------------------------------------+
+   | E_BDATA    | Base64 bad data (could not decode base64 encoded data).                                     |
+   +------------+---------------------------------------------------------------------------------------------+
+   | E_ZDATA    | Zlib corrupted data (could not decompress data).                                            |
+   +------------+---------------------------------------------------------------------------------------------+
+   | E_XDATA    | XML corrupted data (XML document is invalid).                                               |
+   +------------+---------------------------------------------------------------------------------------------+
+   | E_CDATA    | CSV corrupted data (CSV layer data is invalid).                                             |
+   +------------+---------------------------------------------------------------------------------------------+
+   | E_MISSEL   | Missing element, incomplete source (example: a <map> element missing its height attribute). |
+   +------------+---------------------------------------------------------------------------------------------+
+
+   .. note::
+      ``tmx_errno`` is never reset to ``E_NONE``.
+
+   .. note::
+      Error code handling is not necessary as an error message is also generated, see :c:func:`tmx_strerr`.
+
+Error functions
+---------------
+
+.. c:function:: void tmx_perror(const char *prefix)
+
+   Print to stderr a string describing the last error.
+   Equivalent to ``fprintf(stderr, "%s: %s\n", prefix, tmx_strerr());``
+
+.. c:function:: const char* tmx_strerr(void)
+
+   Return a string describing the last error, the returned error message is maximum 256 characters long (including the
+   NULL terminator).
+   Returned value is never NULL.
+
+Example error management
+------------------------
+
+This is an example of how you could handle errors:
+
+.. code-block:: c
+
+   tmx_map *map = NULL;
+   if (!(map = tmx_load("assets/maps/map01.tmx"))) {
+     my_error_handler(tmx_strerr()); /* call user defined error handling function */
+     return -1;
+   }
+   /* process map... */
+   return 0;
diff --git a/doc/src/functions.rst b/doc/src/functions.rst
@@ -128,14 +128,3 @@ Utilities
 
    Call the given callback function for each properties, userdata is forwarded as-is.
    See :c:type:`tmx_property_functor`.
-
-Error reporting
----------------
-
-.. c:function:: void tmx_perror(const char*)
-
-   Print to stderr a string describing the last error.
-
-.. c:function:: const char* tmx_strerr(void)
-
-   Return a string describing the last error.
diff --git a/doc/src/index.rst b/doc/src/index.rst
@@ -14,14 +14,15 @@ libTMX has an ever-changing API (and ABI) therefore the recommended way to use i
 sources of your project.
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    getting-started
    renderer-from-scratch
    build
    datastructure
    functions
    override
+   error
 
 Indices and tables
 ==================