libfdisk: add docs for iterator

diff --git a/libfdisk/src/iter.c b/libfdisk/src/iter.c
index 8e2f342027aa07716b27d54cb54f780bc8358213..9a0b0801cce1a3c8862efcff32f67ac941f6b5b2 100644 (file)
--- a/libfdisk/src/iter.c
+++ b/libfdisk/src/iter.c
@@ -10,8 +10,17 @@
  * @title: Iterator
  * @short_description: unified iterator
  *
- * The iterator keeps the direction and the last position
- * for access to the internal library tables/lists.
+ * The iterator keeps the direction and the last position for access to the
+ * internal library tables/lists.
+ *
+ * It's very unusual to use the same iterator on multiple places in your
+ * application or share the same iterator, for this purpose libfdisk does not
+ * provide reference counting for this object. It's recommended to initialize
+ * the iterator by fdisk_new_iter() at begin of your function and then
+ * fdisk_free_iter() before you return from the function. 
+ *
+ * Don't forget to call fdisk_reset_iter() if you want to use the iterator more
+ * than once.
  */
 #include <stdio.h>
 #include <string.h>