iter: Document guarantees for filter matches argumet

The matches argument is always initialized to CK_TRUE when a filter
is called, and it's up to filters to set it to CK_FALSE. Filters
don't need to set to CK_TRUE.

https://bugzilla.redhat.com/show_bug.cgi?id=985009

diff --git a/p11-kit/iter.c b/p11-kit/iter.c
index 9c22ee0bf609ed94708e08837ba0d1e43047a40d..a59944a204a1a915c770cd436cbb36bb80824ceb 100644 (file)
--- a/p11-kit/iter.c
+++ b/p11-kit/iter.c
@@ -220,6 +220,10 @@ p11_kit_iter_set_session_flags (P11KitIter *iter,
  * indicates through it's <literal>matches</literal> argument that
  * the object should not match, then that object will not be iterated
  * as far as p11_kit_iter_next() is concerned.
+ *
+ * The callbacks will be called with the <literal>matches</literal>
+ * set to <literal>CK_TRUE</literal> and it's up to filters to change
+ * it to <literal>CK_FALSE</literal> when necessary.
  */
 void
 p11_kit_iter_add_callback (P11KitIter *iter,