From f05ccac0a79eb78ff2069974c90092c9fe4f7343 Mon Sep 17 00:00:00 2001
From: nvt-se <nvt-se>
Date: Tue, 21 Oct 2008 13:39:56 +0000
Subject: [PATCH] documented the extra Coffee functions.

---
 core/cfs/cfs-coffee.h | 68 ++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 61 insertions(+), 7 deletions(-)

diff --git a/core/cfs/cfs-coffee.h b/core/cfs/cfs-coffee.h
index 0a2b82711..10560ded2 100644
--- a/core/cfs/cfs-coffee.h
+++ b/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 */