From afaaf9b0d8672af6a5e45cb66338b58f65a8a926 Mon Sep 17 00:00:00 2001
From: lottaviano <lottaviano@38d2e660-2303-0410-9eaa-f027e97ec537>
Date: Fri, 19 Nov 2010 09:23:03 +0000
Subject: [PATCH] doc: Add KFileBlock group and put a reference into KBlock
 docs.

git-svn-id: https://src.develer.com/svnoss/bertos/trunk@4564 38d2e660-2303-0410-9eaa-f027e97ec537
---
 bertos/io/kblock.h      |  3 +++
 bertos/io/kfile_block.h | 23 +++++++++++++++++++++++
 2 files changed, 26 insertions(+)

diff --git a/bertos/io/kblock.h b/bertos/io/kblock.h
index 8bfe384f..56a0bf78 100644
--- a/bertos/io/kblock.h
+++ b/bertos/io/kblock.h
@@ -69,6 +69,9 @@
  * }
  * \endcode
  *
+ * \note The KBlock interface is optimized for block reads. If you need a
+ * file-like access, you can use \ref kfile_block.
+ *
  * \author Francesco Sacchi <batt@develer.com>
  *
  * $WIZ$ module_name = "kblock"
diff --git a/bertos/io/kfile_block.h b/bertos/io/kfile_block.h
index 70fd681e..22b77fdc 100644
--- a/bertos/io/kfile_block.h
+++ b/bertos/io/kfile_block.h
@@ -30,12 +30,33 @@
  *
  * -->
  *
+ * \defgroup kfile_block KFile interface over KBlock
+ * \ingroup core
+ * \{
+ *
  * \brief KFile interface over a KBlock.
  *
  * With this module, you can access a KBlock device
  * with the handy KFile interface.
  * In order to achieve this, the block device must support partial block write.
  *
+ * Make sure you have trimmed the KBlock to avoid overwriting something.
+ * Example:
+ * \code
+ * // init a derived instance of KBlock
+ * // any will do.
+ * Flash flash;
+ * flash_init(&flash, 0);
+ * kblock_trim(&flash.blk, trim_start, internal_flash.blk.blk_cnt - trim_start);
+ *
+ * // now create and initialize the kfile_block instance
+ * KFileBlock kfb;
+ * kfileblock_init(&kfb, &flash.blk);
+ *
+ * // now you can access the Flash in a file like fashion
+ * kfile_read(&kfb.fd, buf, 20);
+ * \endcode
+ *
  * \author Francesco Sacchi <batt@develer.com>
  * \author Daniele Basile <asterix@develer.com>
  *
@@ -71,4 +92,6 @@ typedef struct KFileBlock
  */
 void kfileblock_init(KFileBlock *fb, KBlock *blk);
 
+/** \} */ //defgroup kfile_block
+
 #endif /* IO_KFILE_KBLOCK_H */
-- 
2.25.1