More generic use of event.

[familia.git] / src / storage / family.h

diff --git a/src/storage/family.h b/src/storage/family.h
index 50fb19cfb8757e5debda2424b568b5664a315eb3..96544e196c4f09dfa331b1114636af0884b33d77 100644 (file)
--- a/src/storage/family.h
+++ b/src/storage/family.h
@@ -22,6 +22,12 @@
 
 #include "individual.h"
 
+/**
+ * @file storage/family.h
+ * @brief Code for managing families.
+ *
+ */
+
 enum FFamilyIndividualIndex {
        Individual1,
        Individual2
@@ -48,58 +54,59 @@ struct familia_family {
 };
 
 /**
- * Creates new family structure
- * @return Newly allocated individual.If allocation failed, returns NULL, like
+ * Creates new family structure.
+ * @return Newly allocated @ref familia_family. If allocation failed, returns NULL, like
  *         malloc.
  */
 struct familia_family * familia_family_new();
 
 /**
- * Frees allocated memory of the given family
- * DISCLAIMER! This function does not free memory of linked individuals. You have to
- * remove them manually from storage.
- * @parameter individual free
+ * Frees allocated memory of the given family.
+ * @attention This function does not free memory of linked individuals. You have to
+ * remove them manually from @ref familia_storage, by using @ref familia_storage_free.
+ * @param family family to free
  */
 void familia_family_free(struct familia_family * family);
 
 /**
- * Sets individual1 in the given family
- * @parameter family to set the individual
- * @parameter individual which will be set
+ * Sets parent in the given family.
+ * @param family family to set the parent
+ * @param individual individual which will be a parent in family
+ * @param index individual type which will be set
  */
-void familia_family_set_individual(struct familia_family * family, struct familia_individual * individual, enum FFamilyIndividualIndex index);
+void familia_family_set_parent(struct familia_family * family, struct familia_individual * individual, enum FFamilyIndividualIndex index);
 
 /**
- * Gets individual from the given family
- * @parameter family to get the individual
- * @parameter individual index of which individual get
+ * Gets parent from the given family.
+ * @param family family to get the individual
+ * @param index individual index of which individual get
  */
-struct familia_individual * familia_family_get_individual(struct familia_family * family, enum FFamilyIndividualIndex index);
+struct familia_individual * familia_family_get_parent(struct familia_family * family, enum FFamilyIndividualIndex index);
 
 /**
- * Removes individual from the given family
- * DISCLAIMER! This function does not free memory of linked individuals. You have to
- * remove them manually from storage.
- * @parameter family to remove the individual
- * @parameter individual index of which individual to remove
+ * Removes parent from the given family
+ * @attention This function does not free memory of linked individuals. You have to
+ * remove them manually from @ref familia_storage, by using @ref familia_storage_free.
+ * @param family family to remove the individual
+ * @param index individual index of which individual to remove
  * @return returns removed individual, NULL if such does not exist.
  */
-struct familia_individual * familia_family_remove_individual(struct familia_family * family, enum FFamilyIndividualIndex index);
+struct familia_individual * familia_family_remove_parent(struct familia_family * family, enum FFamilyIndividualIndex index);
 
 /**
  * Adds new child in the given family
  * Automatically sets family as parents in individual variable.
  *
- * @parameter family to set the individual
- * @parameter individual which will be added
+ * @param family family to set the individual
+ * @param individual individual which will be added
  */
 void familia_family_add_child(struct familia_family * family, struct familia_individual * individual);
 
 /**
  * Gets the nth child from the given family
  * Child with index = 0 is the oldest. Bigger the index, the child is younger
- * @parameter family to get the child
- * @parameter individual index of which individual get
+ * @param family family to get the child
+ * @param index individual index of which individual get
  * @return selected child. If index is bigger than child_no of the family
  *         returns NULL.
  */
@@ -107,10 +114,10 @@ struct familia_individual * familia_family_get_child_by_id(struct familia_family
 
 /**
  * Removes child from the given family
- * DISCLAIMER! This function does not free memory of linked children. You have to
- * remove them manually from storage.
- * @parameter family to remove the child
- * @parameter index of which child should be removed
+ * @attention This function does not free memory of linked children. You have to
+ * remove them manually from @ref familia_storage, by using @ref familia_storage_free.
+ * @param family family to remove the child
+ * @param index index of which child should be removed
  * @return removed child. If such does not exist or index is bigger than child_no
  *         of the family, returns NULL.
  */