pdr: pldm_entity_association_tree_visit(): Document preconditions
The preconditions are necessary to infer the success or failure of the
invocation. Callers must inspect the values of the affected objects to
determine the outcome. Make this requirement explicit in the
documentation.
Signed-off-by: Andrew Jeffery <andrew@aj.id.au>
Change-Id: I42649804d342349b3d0ffcb7e0516093ba2d4592
diff --git a/include/libpldm/pdr.h b/include/libpldm/pdr.h
index e2a1968..88608aa 100644
--- a/include/libpldm/pdr.h
+++ b/include/libpldm/pdr.h
@@ -340,6 +340,11 @@
/** @brief Visit and note each entity in the entity association tree
*
+ * @pre `*entities == NULL` and `*size == 0` must hold at the time of invocation.
+ *
+ * Callers must inspect the values of `*entities` and `*size` post-invocation to determine if the
+ * invocation was a success or failure.
+ *
* @param[in] tree - opaque pointer acting as a handle to the tree
* @param[out] entities - pointer to list of pldm_entity's. To be free()'d by
* the caller