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/CHANGELOG.md b/CHANGELOG.md
index ab59e59..de92471 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -53,6 +53,7 @@
9. pdr: pldm_entity_node_get_remote_container_id() is a trivial accessor
10. pdr: pldm_pdr_fru_record_set_find_by_rsi(): Exit early on NULL arguments
11. pdr: pldm_entity_association_tree_init(): Return NULL on failed alloc
+12. pdr: pldm_entity_association_tree_visit(): Document preconditions
### Deprecated
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