You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
270 lines
10 KiB
270 lines
10 KiB
Rebase pull request #543 onto v2.13.1
|
|
|
|
Allows jansson documentation to compile with Sphinx-3.0
|
|
|
|
Squashed commit messages below:
|
|
|
|
|
|
pick 798d40c doc: convert refcounting directive to a class
|
|
|
|
Directive functions are no longer supported in Sphinx-3.0
|
|
but directive classes have been supported since early 1.x
|
|
|
|
|
|
pick 9431889 doc: do not use references for standard C types or file names
|
|
|
|
Use double-backtick quoting instead. It has the same effect
|
|
(because these links had nowhere to link to) but it does not
|
|
result in loud warnings about broken references by default with Sphinx-3.x.
|
|
|
|
|
|
pick c329fd7 doc: add return types for function-like macros
|
|
|
|
The Sphinx-3.0 c:function:: directive requires the return type.
|
|
|
|
Sphinx-3.0 also adds function-like macro support to the c:macro::
|
|
directive, which Sphinx-1.x and Sphinx-2.x do not support, but it
|
|
is probably a good idea to keep compatibility with slightly older
|
|
Sphinx for now.
|
|
|
|
diff --git a/CHANGES b/CHANGES
|
|
index a374a86..256fde1 100644
|
|
--- a/CHANGES
|
|
+++ b/CHANGES
|
|
@@ -8,7 +8,7 @@ Released 2020-05-07
|
|
- Include `jansson_version_str()` and `jansson_version_cmp()` in
|
|
shared library. (#534)
|
|
|
|
- - Include `scripts/` in tarball. (#535)
|
|
+ - Include ``scripts/`` in tarball. (#535)
|
|
|
|
|
|
Version 2.13
|
|
@@ -127,7 +127,7 @@ Released 2018-02-09
|
|
|
|
- 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
|
|
generated using GNU Autotools (#368).
|
|
diff --git a/doc/apiref.rst b/doc/apiref.rst
|
|
index c3a814f..94c5726 100644
|
|
--- a/doc/apiref.rst
|
|
+++ b/doc/apiref.rst
|
|
@@ -145,33 +145,33 @@ Type
|
|
.. function:: int json_typeof(const json_t *json)
|
|
|
|
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.
|
|
|
|
-.. function:: json_is_object(const json_t *json)
|
|
- json_is_array(const json_t *json)
|
|
- json_is_string(const json_t *json)
|
|
- json_is_integer(const json_t *json)
|
|
- json_is_real(const json_t *json)
|
|
- json_is_true(const json_t *json)
|
|
- json_is_false(const json_t *json)
|
|
- json_is_null(const json_t *json)
|
|
+.. function:: int json_is_object(const json_t *json)
|
|
+ int json_is_array(const json_t *json)
|
|
+ int json_is_string(const json_t *json)
|
|
+ int json_is_integer(const json_t *json)
|
|
+ int json_is_real(const json_t *json)
|
|
+ int json_is_true(const json_t *json)
|
|
+ int json_is_false(const json_t *json)
|
|
+ int json_is_null(const json_t *json)
|
|
|
|
These functions (actually macros) return true (non-zero) for values
|
|
of the given type, and false (zero) for values of other types and
|
|
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
|
|
``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
|
|
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``
|
|
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*.
|
|
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
|
|
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
|
|
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
|
|
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::
|
|
|
|
/* obj is a JSON object */
|
|
@@ -764,7 +764,7 @@ allowed in object keys.
|
|
.. 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
|
|
``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.
|
|
|
|
``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``.
|
|
|
|
``i`` (integer) [int]
|
|
- Convert a C :type:`int` to JSON integer.
|
|
+ Convert a C ``int`` to JSON integer.
|
|
|
|
``I`` (integer) [json_int_t]
|
|
Convert a C :type:`json_int_t` to JSON integer.
|
|
|
|
``f`` (real) [double]
|
|
- Convert a C :type:`double` to JSON real.
|
|
+ Convert a C ``double`` to JSON real.
|
|
|
|
``o`` (any value) [json_t \*]
|
|
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.
|
|
|
|
``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.
|
|
|
|
``i`` (integer) [int]
|
|
- Convert a JSON integer to C :type:`int`.
|
|
+ Convert a JSON integer to C ``int``.
|
|
|
|
``I`` (integer) [json_int_t]
|
|
Convert a JSON integer to C :type:`json_int_t`.
|
|
|
|
``f`` (real) [double]
|
|
- Convert a JSON real to C :type:`double`.
|
|
+ Convert a JSON real to C ``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 \*]
|
|
Store a JSON value with no conversion to a :type:`json_t` pointer.
|
|
diff --git a/doc/ext/refcounting.py b/doc/ext/refcounting.py
|
|
index bba2684..e72c481 100644
|
|
--- a/doc/ext/refcounting.py
|
|
+++ b/doc/ext/refcounting.py
|
|
@@ -24,8 +24,8 @@
|
|
"""
|
|
|
|
from docutils import nodes
|
|
+from docutils.parsers.rst import Directive
|
|
|
|
-class refcounting(nodes.emphasis): pass
|
|
|
|
def visit(self, node):
|
|
self.visit_emphasis(node)
|
|
@@ -40,16 +40,25 @@ def html_depart(self, node):
|
|
self.body.append('</em>')
|
|
|
|
|
|
-def refcounting_directive(name, arguments, options, content, lineno,
|
|
- content_offset, block_text, state, state_machine):
|
|
- if arguments[0] == 'borrow':
|
|
- text = 'Return value: Borrowed reference.'
|
|
- elif arguments[0] == 'new':
|
|
- text = 'Return value: New reference.'
|
|
- else:
|
|
- raise Error('Valid arguments: new, borrow')
|
|
+class refcounting(nodes.emphasis):
|
|
+ pass
|
|
+
|
|
+class refcounting_directive(Directive):
|
|
+ has_content = False
|
|
+ required_arguments = 1
|
|
+ optional_arguments = 0
|
|
+ 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):
|
|
app.add_node(refcounting,
|
|
@@ -57,4 +66,4 @@ def setup(app):
|
|
latex=(visit, depart),
|
|
text=(visit, depart),
|
|
man=(visit, depart))
|
|
- app.add_directive('refcounting', refcounting_directive, 0, (1, 0, 0))
|
|
+ app.add_directive('refcounting', refcounting_directive)
|
|
diff --git a/doc/upgrading.rst b/doc/upgrading.rst
|
|
index 9b49046..94ff7de 100644
|
|
--- a/doc/upgrading.rst
|
|
+++ b/doc/upgrading.rst
|
|
@@ -47,13 +47,13 @@ List of Incompatible Changes
|
|
|
|
**Underlying type of JSON integers**
|
|
The underlying C type of JSON integers has been changed from
|
|
- :type:`int` to the widest available signed integer type, i.e.
|
|
- :type:`long long` or :type:`long`, depending on whether
|
|
- :type:`long long` is supported on your system or not. This makes
|
|
+ ``int`` to the widest available signed integer type, i.e.
|
|
+ ``long long`` or ``long``, depending on whether
|
|
+ ``long long`` is supported on your system or not. This makes
|
|
the whole 64-bit integer range available on most modern systems.
|
|
|
|
``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
|
|
implicit type coercion. Only when the full 64-bit range is needed,
|
|
:type:`json_int_t` should be explicitly used.
|
|
@@ -69,8 +69,8 @@ List of Incompatible Changes
|
|
|
|
**Unsigned integers in API functions**
|
|
Version 2.0 unifies unsigned integer usage in the API. All uses of
|
|
- :type:`unsigned int` and :type:`unsigned long` have been replaced
|
|
- with :type:`size_t`. This includes flags, container sizes, etc.
|
|
+ ``unsigned int`` and ``unsigned long`` have been replaced
|
|
+ with ``size_t``. This includes flags, container sizes, etc.
|
|
This should not require source code changes, as both
|
|
- :type:`unsigned int` and :type:`unsigned long` are usually
|
|
- compatible with :type:`size_t`.
|
|
+ ``unsigned int`` and ``unsigned long`` are usually
|
|
+ compatible with ``size_t``.
|