Added documentation for contract block accessor functions

diff --git a/fres/contract/fres_container.c b/fres/contract/fres_container.c
index 6ecc75ad0774d2129cf9418dc68b4131e7eff402..231ee22640e33a41e27e7b1277dd9f4b2aecf89d 100644 (file)
--- a/fres/contract/fres_container.c
+++ b/fres/contract/fres_container.c
@@ -274,7 +274,8 @@ fres_container_del_block(struct fres_container *container,
  * @param type Type of the block to be returned.
  * 
  * @return Pointer to the block or NULL if the block is not present or
- * deserialized.
+ * deserialized. The memory area pointed by this pointer is owned by
+ * the contract. If the user needs to store the block, it must be duplicated.
  */
 void *
 fres_container_get_block(struct fres_container *container,

diff --git a/fres/contract/fres_container.h b/fres/contract/fres_container.h
index a5283e52cbd94da82293025a1c23c431c977f01a..d515882daa0c37fe325d3d091239c48f6c18bdd3 100644 (file)
--- a/fres/contract/fres_container.h
+++ b/fres/contract/fres_container.h
@@ -76,6 +76,19 @@ void *
 fres_container_get_block(struct fres_container *container,
                       enum fres_block_type type);
 
+/**
+ * Macro which defines type-safe container "accessor" functions for
+ * various blocks.
+ *
+ * This macro declares the following inline functions:
+ * - fres_container_add_<type>
+ * - fres_container_get_<type>
+ * - fres_container_del_<type>
+ *
+ * These functions are equivalent to fres_container_add_block(),
+ * fres_container_del_block() and fres_container_get_block() with
+ * appropriate parameters.
+ */
 #define FRES_CONTAINER_ACCESSOR(TYPE, type)                            \
        static inline int                                               \
        fres_container_add_##type(struct fres_container *container,             \

diff --git a/fres/contract/fres_contract.h b/fres/contract/fres_contract.h
index b74d046f22ee9a3f65f3c6f12854a6fa1ca91e15..c186433d07ffa4438efad4ce598100287542e603 100644 (file)
--- a/fres/contract/fres_contract.h
+++ b/fres/contract/fres_contract.h
@@ -44,12 +44,31 @@ struct fres_contract *fres_contract_new(void);
 void fres_contract_destroy(struct fres_contract *contract);
 struct fres_contract *fres_contract_duplicate(struct fres_contract *src);
 
+/** 
+ * Adds a block of the given type to the contract.
+ *
+ * This function uses fres_container_add_block() to do its job.
+ * 
+ * @param contract Where to add the @a block.
+ * @param type Type of contract being added.
+ * @param block Pointer to the malloced block of given @a type.
+ * 
+ * @return Zero on success, -1 on error and errno is set appropriately.
+ */
 static inline int
 fres_contract_add_block(struct fres_contract *contract,
                        enum fres_block_type type, void *block)
 {
        return fres_container_add_block(contract->container, type, block);
 }
+/** 
+ * Deletes a block from the contract and frees it from memory.
+ *
+ * This function uses fres_container_del_block() to do its job.
+ * 
+ * @param contract Where to delete the block.
+ * @param type Type of contract to delete.
+ */
 static inline void
 fres_contract_del_block(struct fres_contract *contract,
                        enum fres_block_type type)
@@ -57,6 +76,19 @@ fres_contract_del_block(struct fres_contract *contract,
        fres_container_del_block(contract->container, type);
 }
 
+/** 
+ * Returns pointer to a contract block of a particular @a type.
+ * 
+ * This function uses fres_container_get_block() to do its job.
+ * 
+ * @param contract
+ * @param type Type of the block to be returned.
+ * 
+ * @return Pointer to the block or NULL if the block is not present or
+ * deserialized. The memory area pointed by this pointer is owned by
+ * the contract. If the user needs to store the block, it must be
+ * duplicated.
+ */
 static inline void *
 fres_contract_get_block(struct fres_contract *contract,
                        enum fres_block_type type)
@@ -73,6 +105,20 @@ fres_contract_get_deadline(const frsh_contract_t *contract,
 void
 fres_contract_print(char *prefix, const struct fres_contract *c);
 
+/**
+ * Macro which defines type-safe contract "accessor" functions for
+ * various blocks.
+ *
+ * This macro declares the following inline functions:
+ * - fres_contract_add_<type>
+ * - fres_contract_get_<type>
+ * - fres_contract_del_<type>
+ *
+ * The defined functions simply use the container "accessor" functions
+ * (usually defined) by #FRES_CONTAINER_ACCESSOR and are equivalent to
+ * fres_contract_add_block(), fres_contract_del_block() and
+ * fres_contract_get_block() with appropriate parameters.
+ */
 #define FRES_CONTRACT_ACCESSOR(type)                                   \
        static inline int                                               \
        fres_contract_add_##type(struct fres_contract *contract,        \