evfuse: comparison src/evsql.h

equal deleted inserted replaced

-:f5037572c326
+:0d6e07f4c9a1
 */
 struct evsql_result;
 /**
 * Various transaction isolation levels for conveniance
+*
+* @see evsql_trans
 */
 enum evsql_trans_type {
 EVSQL_TRANS_DEFAULT,
 EVSQL_TRANS_SERIALIZABLE,
 EVSQL_TRANS_REPEATABLE_READ,
 } flags;
 };
 /**
 * An union to provide storage for the values of small types
+*
+* @see evsql_item
 */
 union evsql_item_value {
 /** 16-bit unsigned integer */
 uint16_t uint16;
 uint64_t uint64;
 };
 /**
 * A generic structure containing the type and value of a query parameter or a result field.
+*
+* @see evsql_query_info
+* @see evsql_query_params
+* @see evsql_result_info
 */
 struct evsql_item {
 /** The "header" containing the type and format */
 struct evsql_item_info info;
 /**
 * Query meta-info, similar to a prepared statement.
 *
 * Contains the literal SQL query and the types of the parameters, but no more.
+*
+* @see evsql_query_exec
 */
 struct evsql_query_info {
 /** The SQL query itself */
 const char *sql;
 struct evsql_item_info params[];
 };
 /**
 * Contains the query parameter types and their actual values
+*
+* @see evsql_query_params
 */
 struct evsql_query_params {
 /** Requested result format for this query. XXX: move elsewhere */
 enum evsql_item_format result_format;
 struct evsql_item list[];
 };
 /**
 * Result layout metadata. This contains the stucture needed to decode result rows.
+*
+* @see evsql_result_begin
 */
 struct evsql_result_info {
 /** XXX: make up something useful to stick here */
 int _unused;
 struct evsql_item_info columns[];
 };
 /**
 * Magic macros for defining param/result info -lists
+*
+* @code
+*  static struct evsql_query_params params = EVSQL_PARAMS(EVSQL_FMT_BINARY) {
+*      EVSQL_PARAM( UINT32 ),
+*      ...,
+*
+*      EVSQL_PARAMS_END
+*  };
+* @endcode
 *
 * @name EVSQL_TYPE/PARAM_*
 * @{
 */
 /**
 * A `struct evsql_item_info` initializer, using FMT_BINARY and the given EVSQL_TYPE_ -suffix.
 *
+* @param typenam the suffix of an evsql_item_type name
+*
 * @see struct evsql_item_info
 * @see enum evsql_item_type
 */
 #define EVSQL_TYPE(typenam)                     { EVSQL_FMT_BINARY, EVSQL_TYPE_ ## typenam  }
 * @see struct evsql_item_info
 */
 #define EVSQL_TYPE_END                          { EVSQL_FMT_BINARY, EVSQL_TYPE_INVALID      }
 /**
-* Initializer block for a `struct evsql_query_params` struct. EVSQL_PARAMS/EVSQL_PARAMS_END should be used as a
+* Initializer block for an evsql_query_params struct
-* pseudo-block with the following layout:
-*
-*  static struct evsql_query_params params = EVSQL_PARAMS(EVSQL_FMT_BINARY) {
-*      EVSQL_PARAM(...),
-*      ...,
-*
-*      EVSQL_PARAMS_END
-*  };
 */
 #define EVSQL_PARAMS(result_fmt)            { result_fmt,
+/**
+* An evsql_item initializer
+*/
 #define EVSQL_PARAM(typenam)                    { EVSQL_TYPE(typenam) }
+/**
+* Include the ending item and terminate the pseudo-block started using #EVSQL_PARAMS
+*/
 #define EVSQL_PARAMS_END                        { EVSQL_TYPE_END } \
 } // <<<
 // @}
 * @see evsql_trans_commit
 */
 typedef void (*evsql_trans_done_cb)(struct evsql_trans *trans, void *arg);
 // @}
+/**
+* Session functions
+*
+* @name evsql_*
+* @{
+*/
 /**
 * Create a new PostgreSQL/libpq (evpq) -based evsql using the given conninfo.
 *
 * The given conninfo must stay valid for the duration of the evsql's lifetime.
 */
 struct evsql *evsql_new_pq (struct event_base *ev_base, const char *pq_conninfo,
 evsql_error_cb error_fn,
 void *cb_arg
 );
+/**
+* Close a connection. Callbacks for waiting queries will not be run.
+*
+* XXX: not implemented yet.
+*
+* @ingroup evsql_*
+* @param evsql the context handle from evsql_new_*
+*/
+void evsql_close (struct evsql *evsql);
+// @}
 /**
 * Query API
 *
 * @name evsql_query_*
 */
 void evsql_result_free (struct evsql_result *res);
 // @}
-/**
-* Close a connection. Callbacks for waiting queries will not be run.
-*
-* XXX: not implemented yet.
-*
-* @ingroup evsql_*
-* @param evsql the context handle from evsql_new_*
-*/
-void evsql_close (struct evsql *evsql);
 #endif /* EVSQL_H */

branch	new-evsql
changeset 53	0d6e07f4c9a1
parent 52	f5037572c326
child 54	7dc8ff496da1