proxmox-mirrors/mirror_frr
1
0
Fork 0
mirror of https://git.proxmox.com/git/mirror_frr synced 2025-04-30 03:00:24 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

doc/developer: use :c:macro: where appropriate

Browse Source 
Sphinx tries to parse :c:function: as function prototype, which doesn't
quite work with macros.

Signed-off-by: David Lamparter <equinox@opensourcerouting.org>
This commit is contained in:
David Lamparter 2021-10-14 19:17:30 +02:00
parent e8713b62d1
commit 8c69c8f743
2 changed files with 14 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
doc/developer/lists.rst
View File

@ -182,7 +182,7 @@ Common iteration macros
The following iteration macros work across all data structures: The following iteration macros work across all data structures:
.. c:function:: frr_each(Z, &head, item) .. c:macro:: frr_each(Z, head, item)
Equivalent to: Equivalent to:
@ -193,7 +193,7 @@ The following iteration macros work across all data structures:
Note that this will fail if the list is modified while being iterated Note that this will fail if the list is modified while being iterated
over. over.
.. c:function:: frr_each_safe(Z, &head, item) .. c:macro:: frr_each_safe(Z, head, item)
Same as the previous, but the next element is pre-loaded into a "hidden" Same as the previous, but the next element is pre-loaded into a "hidden"
variable (named ``Z_safe``.) Equivalent to: variable (named ``Z_safe``.) Equivalent to:
@ -212,7 +212,7 @@ The following iteration macros work across all data structures:
tables is resized while iterating. This will cause items to be tables is resized while iterating. This will cause items to be
skipped or iterated over twice. skipped or iterated over twice.
.. c:function:: frr_each_from(Z, &head, item, from) .. c:macro:: frr_each_from(Z, head, item, from)
Iterates over the list, starting at item ``from``. This variant is "safe" Iterates over the list, starting at item ``from``. This variant is "safe"
as in the previous macro. Equivalent to: as in the previous macro. Equivalent to:
@ -346,7 +346,7 @@ are several functions exposed to insert data:
``item`` must not be ``NULL`` for any of the following functions. ``item`` must not be ``NULL`` for any of the following functions.
.. c:function:: DECLARE_XXX(Z, type, field) .. c:macro:: DECLARE_XXX(Z, type, field)
:param listtype XXX: ``LIST``, ``DLIST`` or ``ATOMLIST`` to select a data :param listtype XXX: ``LIST``, ``DLIST`` or ``ATOMLIST`` to select a data
structure implementation. structure implementation.
@ -403,7 +403,7 @@ Sorted data structures do not need to have an insertion position specified,
therefore the insertion calls are different from unsorted lists. Also, therefore the insertion calls are different from unsorted lists. Also,
sorted lists can be searched for a value. sorted lists can be searched for a value.
.. c:function:: DECLARE_XXX_UNIQ(Z, type, field, compare_func) .. c:macro:: DECLARE_XXX_UNIQ(Z, type, field, compare_func)
:param listtype XXX: One of the following: :param listtype XXX: One of the following:
``SORTLIST`` (single-linked sorted list), ``SKIPLIST`` (skiplist), ``SORTLIST`` (single-linked sorted list), ``SKIPLIST`` (skiplist),
@ -423,7 +423,7 @@ sorted lists can be searched for a value.
``int function(const itemtype *, const itemtype*)``. This function ``int function(const itemtype *, const itemtype*)``. This function
may be static if the list is only used in one file. may be static if the list is only used in one file.
.. c:function:: DECLARE_XXX_NONUNIQ(Z, type, field, compare_func) .. c:macro:: DECLARE_XXX_NONUNIQ(Z, type, field, compare_func)
Same as above, but allow adding multiple items to the list that compare Same as above, but allow adding multiple items to the list that compare
as equal in ``compare_func``. Ordering between these items is undefined as equal in ``compare_func``. Ordering between these items is undefined
@ -477,9 +477,9 @@ sorted lists can be searched for a value.
API for hash tables API for hash tables
------------------- -------------------
.. c:function:: DECLARE_XXX(Z, type, field, compare_func, hash_func) .. c:macro:: DECLARE_HASH(Z, type, field, compare_func, hash_func)
:param listtype XXX: Only ``HASH`` is currently available. :param listtype HASH: Only ``HASH`` is currently available.
:param token Z: Gives the name prefix that is used for the functions :param token Z: Gives the name prefix that is used for the functions
created for this instantiation. ``DECLARE_XXX(foo, ...)`` created for this instantiation. ``DECLARE_XXX(foo, ...)``
gives ``struct foo_item``, ``foo_add()``, ``foo_count()``, etc. Note gives ``struct foo_item``, ``foo_add()``, ``foo_count()``, etc. Note

8
doc/developer/locking.rst
View File

@ -7,7 +7,9 @@ FRR ships two small wrappers around ``pthread_mutex_lock()`` /
``pthread_mutex_unlock``. Use ``#include "frr_pthread.h"`` to get these ``pthread_mutex_unlock``. Use ``#include "frr_pthread.h"`` to get these
macros. macros.
.. c:function:: frr_with_mutex(pthread_mutex_t *mutex) .. c:macro:: frr_with_mutex(mutex)
(With ``pthread_mutex_t *mutex``.)
Begin a C statement block that is executed with the mutex locked. Any Begin a C statement block that is executed with the mutex locked. Any
exit from the block (``break``, ``return``, ``goto``, end of block) will exit from the block (``break``, ``return``, ``goto``, end of block) will
@ -43,7 +45,9 @@ macros.
statement works correctly, FRR coding style requires that this macro always statement works correctly, FRR coding style requires that this macro always
be used with a ``{ ... }`` block. be used with a ``{ ... }`` block.
.. c:function:: frr_mutex_lock_autounlock(pthread_mutex_t *mutex) .. c:macro:: frr_mutex_lock_autounlock(mutex)
(With ``pthread_mutex_t *mutex``.)
Lock mutex and unlock at the end of the current C statement block:: Lock mutex and unlock at the end of the current C statement block::