Update docstrings. No functional change.
* serf.h, serf_bucket_types.h, serf_bucket_util.h:
Update existing docstrings, mostly adding @since references for 1.4
versions. Reformatted some strings and added Doxygen markup on others.
git-svn-id: https://svn.apache.org/repos/asf/serf/trunk@1842251 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/serf.h b/serf.h
index 164632f..272042c 100644
--- a/serf.h
+++ b/serf.h
@@ -395,6 +395,8 @@
/**
* Like serf_connection_closed_t, but applies to incoming connections.
+ *
+ * @since New in 1.4.
*/
typedef apr_status_t (*serf_incoming_closed_t)(
serf_incoming_t *incoming,
@@ -523,6 +525,8 @@
*
* @note the connection is not made immediately. It will be opened on
* the next call to @see serf_context_run.
+ *
+ * @since New in 1.4.
*/
apr_status_t serf_connection_create3(
serf_connection_t **conn,
@@ -628,8 +632,11 @@
apr_pool_t *client_pool);
/* Allows creating a response before the request is completely
- read. Will call the response create function if it hasn't
- been called yet. */
+ * read. Will call the response create function if it hasn't
+ * been called yet.
+ *
+ * @since New in 1.4.
+ */
apr_status_t serf_incoming_response_create(
serf_incoming_request_t *request);
@@ -757,7 +764,11 @@
serf_request_setup_t setup,
void *setup_baton);
-/** The default request priority */
+/**
+ * The default request priority
+ *
+ * @since New in 1.4.
+ */
#define SERF_REQUEST_PRIORITY_DEFAULT 0x1000
/**
@@ -791,13 +802,16 @@
apr_uint16_t priority,
int exclusive);
-/** Returns detected network latency for the @a conn connection. Negative
- * value means that latency is unknwon.
+/**
+ * Returns detected network latency for the @a conn connection. Negative
+ * value means that latency is unknwon.
*/
apr_interval_time_t serf_connection_get_latency(serf_connection_t *conn);
/**
* Returns the number of requests waiting to be sent over connection CONN.
+ *
+ * @since New in 1.4.
*/
unsigned int serf_connection_queued_requests(serf_connection_t *conn);
@@ -806,10 +820,13 @@
* received yet on connection CONN. This includes requests:
* - that are queued but not sent.
* - that have been sent but no response has been completely received yet.
+ *
+ * @since New in 1.4.
*/
unsigned int serf_connection_pending_requests(serf_connection_t *conn);
-/** Check if a @a request has been completely written.
+/**
+ * Check if a @a request has been completely written.
*
* Returns APR_SUCCESS if the request was written completely on the connection.
* Returns APR_EBUSY if the request is not yet or partially written.
@@ -967,8 +984,11 @@
*/
#define SERF_NEWLINE_CRLF_SPLIT 0x0010
-/** Used to indicate that length of remaining data in bucket is unknown. See
+/**
+ * Used to indicate that length of remaining data in bucket is unknown. See
* serf_bucket_type_t->get_remaining().
+ *
+ * @since New in 1.4.
*/
#define SERF_LENGTH_UNKNOWN ((apr_uint64_t) -1)
@@ -1302,10 +1322,10 @@
/* The line is read into this buffer, minus CR/LF.
*
- * NOTE: Before serf 2.0 buffer IS NOT NUL terminated
+ * NOTE: Before serf 1.4 buffer IS NOT NUL terminated
* and @a used should be used to find line length.
*
- * Since serf 2.0 buffer is always NUL terminated.
+ * Since serf 1.4 buffer is always NUL terminated.
**/
char line[SERF_LINEBUF_LIMIT];
@@ -1365,42 +1385,52 @@
Host authn apr_hash_t * (not implemented)
*/
-/* Set a value of type const char * for configuration item CATEGORY+KEY.
- @since New in 1.4.
+/**
+ * Set a value of type const char * for configuration item CATEGORY+KEY.
+ *
+ * @since New in 1.4.
*/
apr_status_t serf_config_set_string(serf_config_t *config,
serf_config_key_t key,
const char *value);
-/* Copy a value of type const char * and set it for configuration item
- CATEGORY+KEY.
- @since New in 1.4.
+/**
+ * Copy a value of type const char * and set it for configuration item
+ * CATEGORY+KEY.
+ *
+ * @since New in 1.4.
*/
apr_status_t serf_config_set_stringc(serf_config_t *config,
serf_config_key_t key,
const char *value);
-/* Set a value of generic type for configuration item CATEGORY+KEY.
- See @a serf_set_config_string for COPY_FLAGS description.
- @since New in 1.4.
+/**
+ * Set a value of generic type for configuration item CATEGORY+KEY.
+ * See @a serf_set_config_string for COPY_FLAGS description.
+ *
+ * @since New in 1.4.
*/
apr_status_t serf_config_set_stringf(serf_config_t *config,
serf_config_key_t key,
apr_pool_t *scratch_pool,
const char *fmt, ...);
-/* Set a value of generic type for configuration item CATEGORY+KEY.
- See @a serf_set_config_string for COPY_FLAGS description.
- @since New in 1.4.
+/**
+ * Set a value of generic type for configuration item CATEGORY+KEY.
+ * See @a serf_set_config_string for COPY_FLAGS description.
+ *
+ * @since New in 1.4.
*/
apr_status_t serf_config_set_object(serf_config_t *config,
serf_config_key_t key,
void *value);
-/* Get the value for configuration item CATEGORY+KEY. The value's type will
- be fixed, see the above table.
- Returns APR_EINVAL when getting a key from a category that this config
- object doesn't contain, APR_SUCCESS otherwise.
- @since New in 1.4.
+/**
+ * Get the value for configuration item CATEGORY+KEY. The value's type will
+ * be fixed, see the above table.
+ * Returns APR_EINVAL when getting a key from a category that this config
+ * object doesn't contain, APR_SUCCESS otherwise.
+ *
+ * @since New in 1.4.
*/
apr_status_t serf_config_get_string(serf_config_t *config,
serf_config_key_t key,
@@ -1410,9 +1440,11 @@
serf_config_key_t key,
void **value);
-/* Remove the value for configuration item CATEGORY+KEY from the configuration
- store.
- @since New in 1.4.
+/**
+ * Remove the value for configuration item CATEGORY+KEY from the configuration
+ * store.
+ *
+ * @since New in 1.4.
*/
apr_status_t serf_config_remove_value(serf_config_t *config,
serf_config_key_t key);
@@ -1453,11 +1485,15 @@
/* TODO: it's not yet possible to define custom layouts */
-/* Create a stream output for log info. This can be used with one of the
- standard streams stderr or stdout.
- LAYOUT should be SERF_LOG_DEFAULT_LAYOUT (there's no alternative for now).
- The lifetime of POOL should be atleast the same as that of CTX, but it can
- be used by multiple contexts. */
+/**
+ * Create a stream output for log info. This can be used with one of the
+ * standard streams stderr or stdout.
+ * LAYOUT should be SERF_LOG_DEFAULT_LAYOUT (there's no alternative for now).
+ * The lifetime of POOL should be atleast the same as that of CTX, but it can
+ * be used by multiple contexts.
+ *
+ * @since New in 1.4.
+ */
apr_status_t serf_logging_create_stream_output(serf_log_output_t **output,
serf_context_t *ctx,
apr_uint32_t level,
@@ -1466,9 +1502,13 @@
FILE *fp,
apr_pool_t *pool);
-/* Define an output handler for a log level and a (set of) log component(s).
- OUTPUT is the object returned by one of the serf_logging_create_XXX_output
- factory functions. */
+/**
+ * Define an output handler for a log level and a (set of) log component(s).
+ * OUTPUT is the object returned by one of the serf_logging_create_XXX_output
+ * factory functions.
+ *
+ * @since New in 1.4.
+ */
apr_status_t serf_logging_add_output(serf_context_t *ctx,
const serf_log_output_t *output);
@@ -1495,6 +1535,8 @@
*
* Note: @a request may be NULL if this response is server-pushed rather than
* specifically requested.
+ *
+ * @since New in 1.4.
*/
typedef apr_status_t (*serf_begin_response_t)(
/* ### args not settled */
@@ -1561,6 +1603,8 @@
* Activate an HTTP request when it reaches the front of the queue.
*
* ### more docco
+ *
+ * @since New in 1.4.
*/
typedef apr_status_t (*serf_http_activate_t)(
serf_bucket_t **body_bkt,
@@ -1597,6 +1641,8 @@
*
* The connection and protocol paresr will be allocated in @a result_pool.
* This function will use @a scratch_pool for temporary allocations.
+ *
+ * @since New in 1.4.
*/
apr_status_t serf_http_protocol_create(
serf_protocol_t **proto,
diff --git a/serf_bucket_types.h b/serf_bucket_types.h
index ffa3fa7..17d8378 100644
--- a/serf_bucket_types.h
+++ b/serf_bucket_types.h
@@ -61,10 +61,12 @@
serf_bucket_t *serf_bucket_request_get_headers(
serf_bucket_t *request);
-/** Transform @a bucket in-place into a request bucket.
+/**
+ * Transform @a bucket in-place into a request bucket.
*
* It is callers responsibility to free resources held by the original
- * bucket */
+ * bucket.
+ */
void serf_bucket_request_become(
serf_bucket_t *bucket,
const char *method,
@@ -596,8 +598,10 @@
const char *cert_path,
const char **password);
-/* Callback type for server certificate status info and OCSP responses.
- Note that CERT can be NULL in case its called from the OCSP callback. */
+/**
+ * Callback type for server certificate status info and OCSP responses.
+ * Note that CERT can be NULL in case its called from the OCSP callback.
+ */
typedef apr_status_t (*serf_ssl_need_server_cert_t)(
void *data,
int failures,
@@ -722,6 +726,8 @@
* The returned string is allocated in @a result_pool.
* Uses @a scratch_pool for temporary allocations.
* Returns NULL on failure.
+ *
+ * @since New in 1.4.
*/
const char *serf_ssl_cert_export2(
const serf_ssl_certificate_t *cert,
@@ -733,6 +739,8 @@
* The returned certificate is allocated in @a result_pool.
* Uses @a scratch_pool for temporary allocations.
* Returns NULL on failure.
+ *
+ * @since New in 1.4.
*/
serf_ssl_certificate_t *serf_ssl_cert_import(
const char *encoded_cert,
@@ -760,6 +768,8 @@
/**
* Load a CRL .pem file from @a file_path and enable CRL checking.
+ *
+ * @since New in 1.4.
*/
apr_status_t serf_ssl_add_crl_from_file(serf_ssl_context_t *ssl_ctx,
const char *file_path,
@@ -769,6 +779,8 @@
* Enable or disable CRL checking of all server certificates.
* @a enabled = 1 to enable CRL checking, 0 to disable CRL checking.
* Default = disabled.
+ *
+ * @since New in 1.4.
*/
apr_status_t serf_ssl_check_crl(serf_ssl_context_t *ssl_ctx,
int enabled);
@@ -778,6 +790,8 @@
* server certificates.
* @a enabled = 1 to enable checking, 0 to disable checking.
* Default = disabled.
+ *
+ * @since New in 1.4.
*/
apr_status_t
serf_ssl_check_cert_status_request(serf_ssl_context_t *ssl_ctx, int enabled);
@@ -803,6 +817,8 @@
/**
* Internal representation of an OCSP request.
+ *
+ * @since New in 1.4.
*/
typedef struct serf_ssl_ocsp_request_t serf_ssl_ocsp_request_t;
@@ -817,6 +833,8 @@
*
* Returns @c NULL on failure, e.g., if @a issuer_cert is not the
* issuer certificate of @a server_cert.
+ *
+ * @since New in 1.4.
*/
serf_ssl_ocsp_request_t *serf_ssl_ocsp_request_create(
const serf_ssl_certificate_t *server_cert,
@@ -834,6 +852,8 @@
* request; see RFC 2560, section A.1.1.
*
* @see serf_ssl_ocsp_request_body_size()
+ *
+ * @since New in 1.4.
*/
const void *serf_ssl_ocsp_request_body(
const serf_ssl_ocsp_request_t *ocsp_request);
@@ -841,6 +861,8 @@
/**
* Returns the size of the DER-encoded OCSP request body.
* @see serf_ssl_ocsp_request_body().
+ *
+ * @since New in 1.4.
*/
apr_size_t serf_ssl_ocsp_request_body_size(
const serf_ssl_ocsp_request_t *ocsp_request);
@@ -852,6 +874,8 @@
* Use @a scratch_pool for temporary allocations.
*
* Returns @c NULL on failure.
+ *
+ * @since New in 1.4.
*/
const char *serf_ssl_ocsp_request_export(
const serf_ssl_ocsp_request_t *ocsp_request,
@@ -866,6 +890,8 @@
* Use @a scratch_pool for temporary allocations.
*
* Returns @c NULL on failure.
+ *
+ * @since New in 1.4.
*/
serf_ssl_ocsp_request_t *serf_ssl_ocsp_request_import(
const char *encoded_ocsp_request,
@@ -874,6 +900,8 @@
/**
* Internal representation of an OCSP response.
+ *
+ * @since New in 1.4.
*/
typedef struct serf_ssl_ocsp_response_t serf_ssl_ocsp_response_t;
@@ -888,6 +916,8 @@
* Use @a scratch_pool for temporary allocations.
*
* Returns @c NULL on failure.
+ *
+ * @since New in 1.4.
*/
serf_ssl_ocsp_response_t *serf_ssl_ocsp_response_parse(
const void *ocsp_response,
@@ -923,6 +953,8 @@
* epoch, i.e., @c APR_TIME_C(0).
*
* Uses @a scratch_pool for temporary allocations.
+ *
+ * @since New in 1.4.
*/
apr_status_t serf_ssl_ocsp_response_verify(
serf_ssl_context_t *ssl_ctx,
@@ -1007,20 +1039,23 @@
/* ==================================================================== */
-/* Creates two buckets, *HEAD and *TAIL, which together contain the output
- of STREAM. If there is enough data in STREAM, HEAD will be a bucket of at
- least MIN_CHUNK_SIZE and will never be larget than MAX_CHUNK_SIZE.
-
- If STREAM is at EOF before MIN_CHUNK_SIZE, HEAD will contain the data,
- while TAIL is immediately at EOF.
-
- HEAD and TAIL will make sure that data read from TAIL will not break the
- data availability promises on HEAD. Passing an existing tail of this
- function as new stream may be handled specificaly, but the read promises
- on all nodes ahead of stream will still hold.
-
- HEAD and TAIL are allocated in STREAM->allocator. STREAM will be
- destroyed when no longer referenced or after EOF.
+/**
+ * Creates two buckets, *HEAD and *TAIL, which together contain the output
+ * of STREAM. If there is enough data in STREAM, HEAD will be a bucket of at
+ * least MIN_CHUNK_SIZE and will never be larget than MAX_CHUNK_SIZE.
+ *
+ * If STREAM is at EOF before MIN_CHUNK_SIZE, HEAD will contain the data,
+ * while TAIL is immediately at EOF.
+ *
+ * HEAD and TAIL will make sure that data read from TAIL will not break the
+ * data availability promises on HEAD. Passing an existing tail of this
+ * function as new stream may be handled specificaly, but the read promises
+ * on all nodes ahead of stream will still hold.
+ *
+ * HEAD and TAIL are allocated in STREAM->allocator. STREAM will be
+ * destroyed when no longer referenced or after EOF.
+ *
+ * @since New in 1.4.
*/
void serf_bucket_split_create(serf_bucket_t **head,
serf_bucket_t **tail,
diff --git a/serf_bucket_util.h b/serf_bucket_util.h
index f6d5e6d..28231ee 100644
--- a/serf_bucket_util.h
+++ b/serf_bucket_util.h
@@ -65,6 +65,8 @@
*
* This function will use the @see read function, when possible optimized by
* the @a peek function to return the requested result.
+ *
+ * @since New in 1.4.
*/
apr_status_t serf_default_readline(serf_bucket_t *bucket, int acceptable,
int *found,
@@ -130,6 +132,8 @@
*
* This function will use the @see read function, when possible optimized by
* the @a peek function to return the requested result.
+ *
+ * @since New in 1.4.
*/
apr_status_t serf_bucket_limited_readline(serf_bucket_t *bucket, int acceptable,
apr_size_t requested, int *found,
@@ -139,6 +143,8 @@
* Default implementation of the @see get_remaining functionality.
*
* This function will just return SERF_LENGTH_UNKNOWN.
+ *
+ * @since New in 1.4.
*/
apr_uint64_t serf_default_get_remaining(
serf_bucket_t *bucket);
@@ -148,6 +154,8 @@
*
* This function will not do anything, it should be used in buckets
* that have no use for the shared config, and do not wrap other bucket(s).
+ *
+ * @since New in 1.4.
*/
apr_status_t serf_default_ignore_config(serf_bucket_t *bucket,
serf_config_t *config);
