FGCOM/jansson
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #543 from ploxiln/sphinx3

Browse Source 
doc: compatibility with Sphinx-3
This commit is contained in:
Petri Lehtinen 2020-08-08 13:15:23 +03:00 committed by GitHub
commit a154389827
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 53 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
CHANGES
View File

@ -8,7 +8,7 @@ Released 2020-05-07
- Include `jansson_version_str()` and `jansson_version_cmp()` in - Include `jansson_version_str()` and `jansson_version_cmp()` in
shared library. (#534) shared library. (#534)
- Include `scripts/` in tarball. (#535) - Include ``scripts/`` in tarball. (#535)
Version 2.13 Version 2.13
@ -127,7 +127,7 @@ Released 2018-02-09
- Work around gcc's -Wimplicit-fallthrough. - Work around gcc's -Wimplicit-fallthrough.
- Fix CMake detection of `sys/types.h` header (#375). - Fix CMake detection of ``sys/types.h`` header (#375).
- Fix `jansson.pc` generated by CMake to be more consistent with the one - Fix `jansson.pc` generated by CMake to be more consistent with the one
generated using GNU Autotools (#368). generated using GNU Autotools (#368).

46
doc/apiref.rst
View File

@ -145,33 +145,33 @@ Type
.. function:: int json_typeof(const json_t *json) .. function:: int json_typeof(const json_t *json)
Return the type of the JSON value (a :type:`json_type` cast to Return the type of the JSON value (a :type:`json_type` cast to
:type:`int`). *json* MUST NOT be *NULL*. This function is actually ``int``). *json* MUST NOT be *NULL*. This function is actually
implemented as a macro for speed. implemented as a macro for speed.
.. function:: json_is_object(const json_t *json) .. function:: int json_is_object(const json_t *json)
json_is_array(const json_t *json) int json_is_array(const json_t *json)
json_is_string(const json_t *json) int json_is_string(const json_t *json)
json_is_integer(const json_t *json) int json_is_integer(const json_t *json)
json_is_real(const json_t *json) int json_is_real(const json_t *json)
json_is_true(const json_t *json) int json_is_true(const json_t *json)
json_is_false(const json_t *json) int json_is_false(const json_t *json)
json_is_null(const json_t *json) int json_is_null(const json_t *json)
These functions (actually macros) return true (non-zero) for values These functions (actually macros) return true (non-zero) for values
of the given type, and false (zero) for values of other types and of the given type, and false (zero) for values of other types and
for *NULL*. for *NULL*.
.. function:: json_is_number(const json_t *json) .. function:: int json_is_number(const json_t *json)
Returns true for values of types ``JSON_INTEGER`` and Returns true for values of types ``JSON_INTEGER`` and
``JSON_REAL``, and false for other types and for *NULL*. ``JSON_REAL``, and false for other types and for *NULL*.
.. function:: json_is_boolean(const json_t *json) .. function:: int json_is_boolean(const json_t *json)
Returns true for types ``JSON_TRUE`` and ``JSON_FALSE``, and false Returns true for types ``JSON_TRUE`` and ``JSON_FALSE``, and false
for values of other types and for *NULL*. for values of other types and for *NULL*.
.. function:: json_boolean_value(const json_t *json) .. function:: int json_boolean_value(const json_t *json)
Alias of :func:`json_is_true()`, i.e. returns 1 for ``JSON_TRUE`` Alias of :func:`json_is_true()`, i.e. returns 1 for ``JSON_TRUE``
and 0 otherwise. and 0 otherwise.
@ -594,7 +594,7 @@ A JSON array is an ordered collection of other JSON values.
Appends all elements in *other_array* to the end of *array*. Appends all elements in *other_array* to the end of *array*.
Returns 0 on success and -1 on error. Returns 0 on success and -1 on error.
.. function:: json_array_foreach(array, index, value) .. function:: void json_array_foreach(array, index, value)
Iterate over every element of ``array``, running the block Iterate over every element of ``array``, running the block
of code that follows each time with the proper values set to of code that follows each time with the proper values set to
@ -732,11 +732,11 @@ allowed in object keys.
recursively merged with the corresponding values in *object* if they are also recursively merged with the corresponding values in *object* if they are also
objects, instead of overwriting them. Returns 0 on success or -1 on error. objects, instead of overwriting them. Returns 0 on success or -1 on error.
.. function:: json_object_foreach(object, key, value) .. function:: void json_object_foreach(object, key, value)
Iterate over every key-value pair of ``object``, running the block Iterate over every key-value pair of ``object``, running the block
of code that follows each time with the proper values set to of code that follows each time with the proper values set to
variables ``key`` and ``value``, of types :type:`const char *` and variables ``key`` and ``value``, of types ``const char *`` and
:type:`json_t *` respectively. Example:: :type:`json_t *` respectively. Example::
/* obj is a JSON object */ /* obj is a JSON object */
@ -764,7 +764,7 @@ allowed in object keys.
.. versionadded:: 2.3 .. versionadded:: 2.3
.. function:: json_object_foreach_safe(object, tmp, key, value) .. function:: void json_object_foreach_safe(object, tmp, key, value)
Like :func:`json_object_foreach()`, but it's safe to call Like :func:`json_object_foreach()`, but it's safe to call
``json_object_del(object, key)`` during iteration. You need to pass ``json_object_del(object, key)`` during iteration. You need to pass
@ -1488,17 +1488,17 @@ arguments.
Output a JSON null value. No argument is consumed. Output a JSON null value. No argument is consumed.
``b`` (boolean) [int] ``b`` (boolean) [int]
Convert a C :type:`int` to JSON boolean value. Zero is converted Convert a C ``int`` to JSON boolean value. Zero is converted
to ``false`` and non-zero to ``true``. to ``false`` and non-zero to ``true``.
``i`` (integer) [int] ``i`` (integer) [int]
Convert a C :type:`int` to JSON integer. Convert a C ``int`` to JSON integer.
``I`` (integer) [json_int_t] ``I`` (integer) [json_int_t]
Convert a C :type:`json_int_t` to JSON integer. Convert a C :type:`json_int_t` to JSON integer.
``f`` (real) [double] ``f`` (real) [double]
Convert a C :type:`double` to JSON real. Convert a C ``double`` to JSON real.
``o`` (any value) [json_t \*] ``o`` (any value) [json_t \*]
Output any given JSON value as-is. If the value is added to an Output any given JSON value as-is. If the value is added to an
@ -1625,20 +1625,20 @@ type whose address should be passed.
Expect a JSON null value. Nothing is extracted. Expect a JSON null value. Nothing is extracted.
``b`` (boolean) [int] ``b`` (boolean) [int]
Convert a JSON boolean value to a C :type:`int`, so that ``true`` Convert a JSON boolean value to a C ``int``, so that ``true``
is converted to 1 and ``false`` to 0. is converted to 1 and ``false`` to 0.
``i`` (integer) [int] ``i`` (integer) [int]
Convert a JSON integer to C :type:`int`. Convert a JSON integer to C ``int``.
``I`` (integer) [json_int_t] ``I`` (integer) [json_int_t]
Convert a JSON integer to C :type:`json_int_t`. Convert a JSON integer to C :type:`json_int_t`.
``f`` (real) [double] ``f`` (real) [double]
Convert a JSON real to C :type:`double`. Convert a JSON real to C ``double``.
``F`` (integer or real) [double] ``F`` (integer or real) [double]
Convert a JSON number (integer or real) to C :type:`double`. Convert a JSON number (integer or real) to C ``double``.
``o`` (any value) [json_t \*] ``o`` (any value) [json_t \*]
Store a JSON value with no conversion to a :type:`json_t` pointer. Store a JSON value with no conversion to a :type:`json_t` pointer.

31
doc/ext/refcounting.py
View File

@ -24,8 +24,8 @@
""" """
from docutils import nodes from docutils import nodes
from docutils.parsers.rst import Directive
class refcounting(nodes.emphasis): pass
def visit(self, node): def visit(self, node):
self.visit_emphasis(node) self.visit_emphasis(node)
@ -40,16 +40,25 @@ def html_depart(self, node):
self.body.append('</em>') self.body.append('</em>')
def refcounting_directive(name, arguments, options, content, lineno, class refcounting(nodes.emphasis):
content_offset, block_text, state, state_machine): pass
if arguments[0] == 'borrow':
text = 'Return value: Borrowed reference.' class refcounting_directive(Directive):
elif arguments[0] == 'new': has_content = False
text = 'Return value: New reference.' required_arguments = 1
else: optional_arguments = 0
raise Error('Valid arguments: new, borrow') final_argument_whitespace = False
def run(self):
if self.arguments[0] == 'borrow':
text = 'Return value: Borrowed reference.'
elif self.arguments[0] == 'new':
text = 'Return value: New reference.'
else:
raise Error('Valid arguments: new, borrow')
return [refcounting(text, text)]
return [refcounting(text, text)]
def setup(app): def setup(app):
app.add_node(refcounting, app.add_node(refcounting,
@ -57,4 +66,4 @@ def setup(app):
latex=(visit, depart), latex=(visit, depart),
text=(visit, depart), text=(visit, depart),
man=(visit, depart)) man=(visit, depart))
app.add_directive('refcounting', refcounting_directive, 0, (1, 0, 0)) app.add_directive('refcounting', refcounting_directive)

16
doc/upgrading.rst
View File

@ -47,13 +47,13 @@ List of Incompatible Changes
**Underlying type of JSON integers** **Underlying type of JSON integers**
The underlying C type of JSON integers has been changed from The underlying C type of JSON integers has been changed from
:type:`int` to the widest available signed integer type, i.e. ``int`` to the widest available signed integer type, i.e.
:type:`long long` or :type:`long`, depending on whether ``long long`` or ``long``, depending on whether
:type:`long long` is supported on your system or not. This makes ``long long`` is supported on your system or not. This makes
the whole 64-bit integer range available on most modern systems. the whole 64-bit integer range available on most modern systems.
``jansson.h`` has a typedef :type:`json_int_t` to the underlying ``jansson.h`` has a typedef :type:`json_int_t` to the underlying
integer type. :type:`int` should still be used in most cases when integer type. ``int`` should still be used in most cases when
dealing with smallish JSON integers, as the compiler handles dealing with smallish JSON integers, as the compiler handles
implicit type coercion. Only when the full 64-bit range is needed, implicit type coercion. Only when the full 64-bit range is needed,
:type:`json_int_t` should be explicitly used. :type:`json_int_t` should be explicitly used.
@ -69,8 +69,8 @@ List of Incompatible Changes
**Unsigned integers in API functions** **Unsigned integers in API functions**
Version 2.0 unifies unsigned integer usage in the API. All uses of Version 2.0 unifies unsigned integer usage in the API. All uses of
:type:`unsigned int` and :type:`unsigned long` have been replaced ``unsigned int`` and ``unsigned long`` have been replaced
with :type:`size_t`. This includes flags, container sizes, etc. with ``size_t``. This includes flags, container sizes, etc.
This should not require source code changes, as both This should not require source code changes, as both
:type:`unsigned int` and :type:`unsigned long` are usually ``unsigned int`` and ``unsigned long`` are usually
compatible with :type:`size_t`. compatible with ``size_t``.