From: Donald Sharp <sharpd@cumulusnetworks.com>
Date: Tue, 30 Apr 2019 21:56:05 +0000 (-0400)
Subject: doc: Some minor doc cleanup for new data structures
X-Git-Tag: base_7.2~373^2~5
X-Git-Url: https://git.puffer.fish/?a=commitdiff_plain;h=21fee7927f427a02ed814396505f9654a2e1bcce;p=matthieu%2Ffrr.git

doc: Some minor doc cleanup for new data structures

Noticed during attempts at usage that the documentation
needed a couple small updates:

1) Tell the user which header to include
2) Some functions want the address of the data structure

Signed-off-by: Donald Sharp <sharpd@cumulusnetworks.com>
---

diff --git a/doc/developer/lists.rst b/doc/developer/lists.rst
index 6d60420b2f..987b3b7f4f 100644
--- a/doc/developer/lists.rst
+++ b/doc/developer/lists.rst
@@ -119,6 +119,8 @@ The common setup pattern will look like this:
 
 .. code-block:: c
 
+   #include <typesafe.h>
+
    PREDECL_XXX(Z)
    struct item {
        int otherdata;
@@ -159,26 +161,26 @@ Common iteration macros
 
 The following iteration macros work across all data structures:
 
-.. c:function:: for_each(Z, head, item)
+.. c:function:: for_each(Z, &head, item)
 
    Equivalent to:
 
    .. code-block:: c
 
-      for (item = Z_first(head); item; item = Z_next(head, item))
+      for (item = Z_first(&head); item; item = Z_next(&head, item))
 
    Note that this will fail if the list is modified while being iterated
    over.
 
-.. c:function:: for_each_safe(Z, head, item)
+.. c:function:: for_each_safe(Z, &head, item)
 
    Same as the previous, but the next element is pre-loaded into a "hidden"
    variable (named ``Z_safe``.)  Equivalent to:
 
    .. code-block:: c
 
-      for (item = Z_first(head); item; item = next) {
-          next = Z_next_safe(head, item);
+      for (item = Z_first(&head); item; item = next) {
+          next = Z_next_safe(&head, item);
           ...
       }
 
@@ -189,7 +191,7 @@ The following iteration macros work across all data structures:
       tables is resized while iterating.  This will cause items to be
       skipped or iterated over twice.
 
-.. c:function:: for_each_from(Z, head, item, from)
+.. c:function:: for_each_from(Z, &head, item, from)
 
    Iterates over the list, starting at item ``from``.  This variant is "safe"
    as in the previous macro.  Equivalent to:
@@ -197,7 +199,7 @@ The following iteration macros work across all data structures:
    .. code-block:: c
 
       for (item = from; item; item = from) {
-          from = Z_next_safe(head, item);
+          from = Z_next_safe(&head, item);
           ...
       }