changeset 3906:1316d3d078be

libpersist: doc
author Alexandre Becoulet <alexandre.becoulet@free.fr>
date Wed, 18 Apr 2018 17:24:27 +0200
parents ce37251278b7
children 16ebad6b7db4
files doc/header_list.mk doc/top.mkdoc libpersist/include/persist/persist.h libpersist/persist.config libpersist/persist.mkdoc
diffstat 5 files changed, 56 insertions(+), 50 deletions(-) [+]
line wrap: on
line diff
--- a/doc/header_list.mk	Wed Apr 18 15:49:41 2018 +0200
+++ b/doc/header_list.mk	Wed Apr 18 17:24:27 2018 +0200
@@ -1,6 +1,6 @@
 
 BASE_MODULES += libfdt libpthread libm libvfs hexo mutek libc   \
-libdevice libnetwork libinet libble
+libdevice libnetwork libinet libble libpersist
 
 ARCH_HEADER= arch/hexo/atomic.h arch/hexo/lock.h	\
 	arch/hexo/types.h
--- a/doc/top.mkdoc	Wed Apr 18 15:49:41 2018 +0200
+++ b/doc/top.mkdoc	Wed Apr 18 17:24:27 2018 +0200
@@ -28,6 +28,7 @@
 @include ../libtermui/libtermui.mkdoc
 @include ../libgomp/libgomp.mkdoc
 @include ../liblua/liblua.mkdoc
+@include ../libpersist/persist.mkdoc
 
 @include ../arch/arch.mkdoc
 @include ../cpu/cpu.mkdoc
--- a/libpersist/include/persist/persist.h	Wed Apr 18 15:49:41 2018 +0200
+++ b/libpersist/include/persist/persist.h	Wed Apr 18 17:24:27 2018 +0200
@@ -21,54 +21,9 @@
 
 /**
    @file
-   @module {Libraries::Persist}
-   @short Persistent configuration device driver
-
-   @section {Description}
-
-   The @tt persist library offers a basic and simple
-   configuration storage service in flash memory.
-
-   Operations involve:
-   @list
-   @item Read a value,
-   @item Write a value,
-   @item Delete a value,
-   @item Pack storage backend (reclaim unused space),
-   @item Erase storage.
-   @end list
-
-   @tt persist devices can hold up to 2^16 values, distinguished
-   through their UID (unique identifier).
-
-   Stored values must have a static declaration (@see
-   persist_descriptor_s).  Values may be of one of two types:
-   @list
-   @item Blobs, binary objects read/write verbatim;
-   @item Counters, 64 bit values that can either be added to or erased.
-   @end list
-
-   In order to be able to share a declaration among various similar
-   values, requests may set an @tt uid_offset that gets added to the
-   descriptor's UID when looking up value in storage backend.
-
-   Storage backend takes all possible measures to ensure value
-   validity and durability.  In particular, special care is taken to
-   ensure no data is lost in case of power outage during write phases.
-
-   Size of blobs is known in advance and is part of their declaration.
-   They cannot extend beyond their preallocated size.
-
-   Size of counters must be at least 8 bytes, They make no interest
-   under 9 bytes.  Any byte beyond 8-th serves as an optimization on
-   increment operations: increments are done in-place using spare bits
-   as an unary value that adds to the counter.  This makes sense on
-   flash-based storage backends where a page-erase operation is
-   required before writing new data.  Optimal size to allocate to a
-   counter is a usage-dependant tradeof.
-
-   @end section
- */
+   @module {Libraries::Persistent configuration service}
+   @short Persistent configuration library
+*/
 
 #ifndef __PERSIST_H__
 #define __PERSIST_H__
--- a/libpersist/persist.config	Wed Apr 18 15:49:41 2018 +0200
+++ b/libpersist/persist.config	Wed Apr 18 17:24:27 2018 +0200
@@ -2,5 +2,5 @@
 %config CONFIG_PERSIST
   desc Provide support for persitent storage of values in flash memory
   flags auto
-  module libpersist Libraries::Persist
+  module libpersist Libraries::Persistent configuration service
 %config end
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/libpersist/persist.mkdoc	Wed Apr 18 17:24:27 2018 +0200
@@ -0,0 +1,50 @@
+
+@moduledef{Persistent configuration service} {Libraries}
+ @short Persistent configuration storage library
+
+   The @tt persist library offers a basic and simple
+   configuration storage service in flash memory.
+
+   Operations involve:
+   @list
+   @item Read a value,
+   @item Write a value,
+   @item Delete a value,
+   @item Pack storage backend (reclaim unused space),
+   @item Erase storage.
+   @end list
+
+   @tt persist devices can hold up to 2^16 values, distinguished
+   through their UID (unique identifier).
+
+   Stored values must have a static declaration (@see
+   persist_descriptor_s).  Values may be of one of two types:
+   @list
+   @item Blobs, binary objects read/write verbatim;
+   @item Counters, 64 bit values that can either be added to or erased.
+   @end list
+
+   In order to be able to share a declaration among various similar
+   values, requests may set an @tt uid_offset that gets added to the
+   descriptor's UID when looking up value in storage backend.
+
+   Storage backend takes all possible measures to ensure value
+   validity and durability.  In particular, special care is taken to
+   ensure no data is lost in case of power outage during write phases.
+
+   Size of blobs is known in advance and is part of their declaration.
+   They cannot extend beyond their preallocated size.
+
+   Size of counters must be at least 8 bytes, They make no interest
+   under 9 bytes.  Any byte beyond 8-th serves as an optimization on
+   increment operations: increments are done in-place using spare bits
+   as an unary value that adds to the counter.  This makes sense on
+   flash-based storage backends where a page-erase operation is
+   required before writing new data.  Optimal size to allocate to a
+   counter is a usage-dependant tradeof.
+
+@end moduledef
+
+@parse{
+persist/persist.h
+}