documented the extra Coffee functions.

core/cfs/cfs-coffee.h

@@ -1,3 +1,8 @@
+/**
+ * \addtogroup cfs
+ * @{
+ */
+
 /*
  * Copyright (c) 2008, Swedish Institute of Computer Science
  * All rights reserved.
@@ -30,20 +35,69 @@
  *
  */
 
-/**
- * \file
- *	Coffee main header.
- * \author
- * 	Nicolas Tsiftes <nvt@sics.se>
- */
-
 #ifndef CFS_COFFEE_H
 #define CFS_COFFEE_H
 
+/**
+ * \file
+ *	Header for the Coffee file system.
+ * \author
+ * 	Nicolas Tsiftes <nvt@sics.se>
+ *
+ * \name Functions called from application programs
+ * @{
+ */
+
+/**
+ * \brief Remove a file.
+ * \param name The filename.
+ * \return 0 on success, -1 on failure.
+ *
+ * Coffee removes files by marking them as obsolete. Therefore, the 
+ * space is not guaranteed to be reclaimed immediately, but must be 
+ * sweeped by the garbage collector. The garbage collector is called 
+ * once a file reservation request cannot be granted.
+ */
 int cfs_coffee_remove(const char *name);
+
+/**
+ * \brief Reserve space for a file.
+ * \param name The filename.
+ * \param size The size of the file.
+ * \return 0 on success, -1 on failure.
+ *
+ * Coffee uses sequential page structures for append-only files. The 
+ * sequential structure can be reserved with a certain. If no reservation 
+ * has been done, files will be set to a default size once opened for 
+ * the first time.
+ */
 int cfs_coffee_reserve(const char *name, uint32_t size);
+
+/**
+ * \brief Configure the on-demand log file.
+ * \param file
+ * \param log_size
+ * \param log_entry_size
+ * \return 0 on success, -1 on failure.
+ *
+ * When file data is first modified, Coffee creates a micro log for the 
+ * file. The micro log stores a table of modifications where each record 
+ * is of log_entry_size.
+ */
 int cfs_coffee_configure_log(const char *file, unsigned log_size,
 	unsigned log_entry_size);
+
+/**
+ * \brief Format the storage area assigned to Coffee.
+ * \return 0 on success, -1 on failure.
+ *
+ * Coffee formats the underlying storage by setting all bits to zero.
+ * This operation is required prior to using Coffee for the first time
+ * in a system.
+ */
 int cfs_coffee_format(void);
 
+/** @} */
+/** @} */
+
 #endif /* !COFFEE_H */