[magi]

3 files changed, 89 insertions, 40 deletions

diff --git a/include/magi/loadfile.h b/include/magi/loadfile.h
index 942c298..b485ea1 100644
--- a/include/magi/loadfile.h
+++ b/include/magi/loadfile.h
@@ -1,29 +1,55 @@
 #ifndef MAGI_INCLUDED_LOADFILE
 #define MAGI_INCLUDED_LOADFILE
-
+/** @file loadfile.h
+ * @brief Simple callback to load files.
+ *
+ * Generally satisfies task of receiving files.  Fill #magi_loadfiles table
+ * via #magi_loadfiles_add, specifying which file-parameter to load into which
+ * path, and what are size limitations for it.  When table is complete setup
+ * your request to use this callback with #magi_request_setup_loadfiles.
+ *
+ * @note This module is optional.
+ */
 #include "request.h"
 
 
-typedef struct magi_loadfile {
-    const char *param_name; /* Form field name, in which file is expected. */
-    const char *location;   /* Location to load file in. */
-    int         maximum;    /* Limit in bytes. Null <=> unlimited. */
-} magi_loadfile;
-
-typedef struct magi_loadfiles {
-    int            count;
-    magi_loadfile *files;
-} magi_loadfiles;
-
+/** @brief Rule of loading single file.
+ * 
+ * There is no need to form or edit it directly. */
+struct magi_loadfile {
+    const char *name;  /**<@brief Form field to load file from. */
+    const char *path;  /**<@brief Path to load file in. */
+    int         max;   /**<@brief Limit in bytes. Null means unlimited. */
+};
+typedef struct magi_loadfile magi_loadfile;
+
+/** @brief Table of rules for loading files.
+ * 
+ * Set @c count and @c files as null to initialize. */
+struct magi_loadfiles {
+    int            count; /**<@brief Size of @c files.*/
+    magi_loadfile *files; /**<@brief Dynamic array of rules to load files. */
+};
+typedef struct magi_loadfiles magi_loadfiles;
+
+/** @brief Add entity into @p table.
+ * @param[in,out] table is the table to add into.
+ * @param[in] name is the form field name to load file from.
+ * @param[in] path to load file in.
+ * @param[in] max is limit in bytes (give null to unlimit). */
 void magi_loadfiles_add(magi_loadfiles *table,
                         const char     *name,
                         const char     *path,
                         int             max);
 
-void magi_loadfiles_destroy(magi_loadfiles *table);
+/** @brief Free memmory used by @p table.
+ * @warning Request using @p table will become invalid.
+ * @param[in,out] table to be destructed. */
+void magi_loadfiles_free(magi_loadfiles *table);
 
-/* Setup request callback with files loaded into corresponding to their
- * parameter names locations; paths are in magi_loadfiles struct. */
+/** @brief Setup @p request to use loadfiles callback with @p table.
+ * @param[in,out] request to setup using loadfiles callback.
+ * @param[in] table to use in loadfiles callback. */
 void magi_request_setup_loadfiles(magi_request   *request,
                                   magi_loadfiles *table);
 
diff --git a/include/magi/param.h b/include/magi/param.h
index 6fd3b67..de39ff6 100644
--- a/include/magi/param.h
+++ b/include/magi/param.h
@@ -1,33 +1,41 @@
 #ifndef MAGI_INCLUDED_PARAM
 #define MAGI_INCLUDED_PARAM
 /** @file param.h
- * @brief blah...
- *
- * blah-blah...
+ * @brief Parameter as name-value pair.
  */
 
 
-typedef struct magi_param {
-    /* All pointers must be valid as 'free' arguments. */
-    char *name;
-    char *data;
-} magi_param;
-
-typedef struct magi_param_list {
-    struct magi_param_list *next; /* Must be valid as 'free' argument. */
-    magi_param              item;
-} magi_param_list;
-
+/** @brief Parameter as name-value pair. */
+struct magi_param {
+    char *name;  /**<@brief Cannot be null. */
+    char *data;  /**<@brief Cannot be null. */
+};
+typedef struct magi_param magi_param;
 
-/* Addition of item to top of list. Null <=> error. */
-int magi_param_list_add(magi_param_list **list,
-                        magi_param       *item);
-
-/* Data of the first node in list: node.name == name; else null. */
-char *magi_param_list_get(magi_param_list *list, const char *name);
+/** @brief Parameters collection.
+ *
+ * Implemented as linked list. */
+struct magi_params {
+    struct magi_params *next;  /**<@brief Pointer to next parameter. */
+    magi_param          item;  /**<@brief Top parameter. */
+};
+typedef struct magi_params magi_params;
+
+
+/** @brief Add @p newitem to @p params.
+ * @param[in,out] params to add into.
+ * @param[in] newitem to add onto top of @p params. */
+void magi_params_add(magi_params **params, magi_param *newitem);
+
+/** @brief Get data of parameter from @p params with @p name.
+ * @param[in] params to search in.
+ * @param[in] name of needed parameter.
+ * @return data of the first from top of @p params parameter with @p name,
+ *         null only if no parameter with @p name is in @p params. */
+char *magi_params_get(magi_param_list *params, const char *name);
 
 /* Freeing and invalidation of list. */
-void magi_param_list_destroy(magi_param_list *list);
+void magi_params_free(magi_params *params);
 
 
 #endif
diff --git a/include/magi/urlenc.h b/include/magi/urlenc.h
index 10fee1d..aa21f3e 100644
--- a/include/magi/urlenc.h
+++ b/include/magi/urlenc.h
@@ -1,14 +1,29 @@
 #ifndef MAGI_INCLUDED_URLENC
 #define MAGI_INCLUDED_URLENC
 /** @file urlenc.h
- * @brief Realisation of url-encoding.
+ * @brief Realisation of URL-encoding.
  *
- * Can be helpful in forming urls in response.
+ * Can be helpful in forming urls in response.  Use #magi_urlenc for
+ * encoding itself and #magi_urlenc_size to find what the size of code
+ * will be.
+ *
+ * RFC 3986 describes URL-encoding.  Briefly it is changing every space into
+ * plus sign and every not alpha-numerical and not @c "~-._" character into
+ * percent sign followed by hexadecimal representation of given character.
+ * 
+ * @note This module is optional.
  */
 
 
-/* 'code' from urlenc must have size of at least magi_urlenc_size(plain). */
-int  magi_urlenc_size(const char *plain);
+/** @brief Count URL-code size for @p plain.
+ * @param[in] plain is a text to count code size for.
+ * @return size of URL-code of @p plain. */
+int magi_urlenc_size(const char *plain);
+
+/** @brief Encode @p plain to url-code @p code.
+ * @warning @p code must be at least size of #magi_urlenc_size(@p plain).
+ * @param[in] plain is a text to be encoded.
+ * @param[out] code will be filled with URL-code of @p plain. */
 void magi_urlenc(const char *plain, char *code);