From: Michal Vaner <vorner@ucw.cz>
Date: Wed, 22 Oct 2008 11:43:54 +0000 (+0200)
Subject: ucw docs: init and commit hooks described in-place
X-Git-Tag: holmes-import~254
X-Git-Url: http://mj.ucw.cz/gitweb/?a=commitdiff_plain;h=a804ff2ac5532f590f9e307869bdb2f5974c8b4f;p=libucw.git

ucw docs: init and commit hooks described in-place
---

diff --git a/ucw/conf.h b/ucw/conf.h
index 42bf0c94..e2619eea 100644
--- a/ucw/conf.h
+++ b/ucw/conf.h
@@ -152,9 +152,29 @@ struct cf_section {			/** A section. **/
  * macros to create arrays.
  */
 #define CF_TYPE(s)	.size = sizeof(s)
-#define CF_INIT(f)	.init = (cf_hook*) f		/** Init <<hooks,hook>>. **/
-#define CF_COMMIT(f)	.commit = (cf_hook*) f		/** Commit <<hooks,hook>>. **/
-#define CF_COPY(f)	.copy = (cf_copier*) f		/** <<hooks,Copy function>>. **/
+/**
+ * An init <<hooks,hook>>.
+ * You can use this to initialize dynamically allocated items (for a dynamic array or list).
+ * The hook returns an error message or NULL if everything was OK.
+ */
+#define CF_INIT(f)	.init = (cf_hook*) f
+/**
+ * A commit <<hooks,hook>>.
+ * You can use this one to check sanity of loaded data and postprocess them.
+ * You must call @cf_journal_block() if you change anything.
+ *
+ * Return error message or NULL if everything went OK.
+ **/
+#define CF_COMMIT(f)	.commit = (cf_hook*) f
+/**
+ * A <<hooks,copy function>>.
+ * You need to provide one for too complicated sections where a memcpy is not
+ * enough to copy it properly. It happens, for example, when you have a dynamically
+ * allocated section containing a list of other sections.
+ *
+ * You return an error message or NULL if you succeed.
+ **/
+#define CF_COPY(f)	.copy = (cf_copier*) f		/**  **/
 #define CF_ITEMS	.cfg = ( struct cf_item[] )	/** List of sub-items. **/
 #define CF_END		{ .cls = CC_END }		/** End of the structure. **/
 /***