serf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From br...@apache.org
Subject svn commit: r1842251 - in /serf/trunk: serf.h serf_bucket_types.h serf_bucket_util.h
Date Fri, 28 Sep 2018 14:14:52 GMT
Author: brane
Date: Fri Sep 28 14:14:52 2018
New Revision: 1842251

URL: http://svn.apache.org/viewvc?rev=1842251&view=rev
Log:
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.

Modified:
    serf/trunk/serf.h
    serf/trunk/serf_bucket_types.h
    serf/trunk/serf_bucket_util.h

Modified: serf/trunk/serf.h
URL: http://svn.apache.org/viewvc/serf/trunk/serf.h?rev=1842251&r1=1842250&r2=1842251&view=diff
==============================================================================
--- serf/trunk/serf.h (original)
+++ serf/trunk/serf.h Fri Sep 28 14:14:52 2018
@@ -395,6 +395,8 @@ typedef void (*serf_connection_closed_t)
 
 /**
  * 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 @@ apr_status_t serf_connection_create2(
  *
  * @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_status_t serf_incoming_create2(
     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_t *serf_connection_priority
     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 @@ void serf_connection_request_prioritize(
                                         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 @@ unsigned int serf_connection_queued_requ
  * 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 @@ serf_bucket_t *serf_request_bucket_reque
  */
 #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 @@ typedef struct serf_linebuf_t {
 
     /* 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 @@ typedef enum serf_config_categories_t {
    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 @@ apr_status_t serf_config_get_object(serf
                                     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 @@ typedef struct serf_log_layout_t serf_lo
 
 /* 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 @@ apr_status_t serf_logging_create_stream_
                                                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 @@ typedef struct serf_queue_item_t serf_qu
  *
  * 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 @@ struct serf_protocol_type_t {
  * 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 @@ typedef apr_status_t (*serf_http_activat
  *
  * 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,

Modified: serf/trunk/serf_bucket_types.h
URL: http://svn.apache.org/viewvc/serf/trunk/serf_bucket_types.h?rev=1842251&r1=1842250&r2=1842251&view=diff
==============================================================================
--- serf/trunk/serf_bucket_types.h (original)
+++ serf/trunk/serf_bucket_types.h Fri Sep 28 14:14:52 2018
@@ -61,10 +61,12 @@ void serf_bucket_request_set_CL(
 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 @@ typedef apr_status_t (*serf_ssl_need_cer
     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 @@ const char *serf_ssl_cert_export(
  * 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 @@ const char *serf_ssl_cert_export2(
  * 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 @@ apr_status_t serf_ssl_trust_cert(
 
 /**
  * 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 @@ apr_status_t serf_ssl_add_crl_from_file(
  * 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 @@ apr_status_t serf_ssl_check_crl(serf_ssl
  * 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 @@ serf_ssl_context_t *serf_bucket_ssl_encr
 
 /**
  * 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 @@ typedef struct serf_ssl_ocsp_request_t s
  *
  * 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 @@ serf_ssl_ocsp_request_t *serf_ssl_ocsp_r
  * 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 @@ const void *serf_ssl_ocsp_request_body(
 /**
  * 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 @@ apr_size_t serf_ssl_ocsp_request_body_si
  * 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 @@ const char *serf_ssl_ocsp_request_export
  * 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 @@ serf_ssl_ocsp_request_t *serf_ssl_ocsp_r
 
 /**
  * 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 @@ typedef struct serf_ssl_ocsp_response_t
  * 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 @@ serf_ssl_ocsp_response_t *serf_ssl_ocsp_
  * 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 @@ serf_bucket_t *serf_bucket_prefix_create
 
 /* ==================================================================== */
 
-/* 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,

Modified: serf/trunk/serf_bucket_util.h
URL: http://svn.apache.org/viewvc/serf/trunk/serf_bucket_util.h?rev=1842251&r1=1842250&r2=1842251&view=diff
==============================================================================
--- serf/trunk/serf_bucket_util.h (original)
+++ serf/trunk/serf_bucket_util.h Fri Sep 28 14:14:52 2018
@@ -65,6 +65,8 @@ apr_status_t serf_default_read_iovec(
  *
  * 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 @@ void serf_default_destroy_and_data(
  *
  * 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 @@ apr_status_t serf_bucket_limited_readlin
  * 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 @@ apr_uint64_t serf_default_get_remaining(
  *
  * 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);



Mime
View raw message