Tidy comments in librsync.h

1 files changed, 116 insertions, 164 deletions

diff --git a/src/librsync.h b/src/librsync.h
index 257da49..98b3c29 100644
--- a/src/librsync.h
+++ b/src/librsync.h
@@ -1,4 +1,4 @@
-/*=                    -*- c-basic-offset: 4; indent-tabs-mode: nil; -*-
+/*= -*- c-basic-offset: 4; indent-tabs-mode: nil; -*-
  *
  * librsync -- library for network deltas
  *
@@ -43,12 +43,11 @@ extern "C" {
 #endif
 
 /** Library version string.
- * \see \ref versioning
- */
+ *
+ * \sa \ref versioning */
 extern char const rs_librsync_version[];
 
-/** Summary of the licence for librsync.
- */
+/** Summary of the licence for librsync. */
 extern char const rs_licence_string[];
 
 typedef uint8_t rs_byte_t;
@@ -67,22 +66,17 @@ typedef intmax_t rs_long_t;
                            */
 
 
-/**
- * A uint32 magic number, emitted in bigendian/network order at the start of
- * librsync files.
- **/
+/** A uint32 magic number, emitted in bigendian/network order at the start of
+ * librsync files. */
 typedef enum {
-    /**
-     * A delta file.
+    /** A delta file.
      *
      * At present, there's only one delta format.
      *
-     * The four-byte literal \c "rs\x026".
-     **/
+     * The four-byte literal \c "rs\x026". */
     RS_DELTA_MAGIC          = 0x72730236,
 
-    /**
-     * A signature file with MD4 signatures.
+    /** A signature file with MD4 signatures.
      *
      * Backward compatible with
      * librsync < 1.0, but strongly deprecated because it creates a security
@@ -91,29 +85,24 @@ typedef enum {
      *
      * The four-byte literal \c "rs\x016".
      *
-     * \see rs_sig_begin()
-     **/
+     * \sa rs_sig_begin() */
     RS_MD4_SIG_MAGIC        = 0x72730136,
 
-    /**
-     * A signature file using the BLAKE2 hash. Supported from librsync 1.0.
+    /** A signature file using the BLAKE2 hash. Supported from librsync 1.0.
      *
      * The four-byte literal \c "rs\x017".
      *
-     * \see rs_sig_begin()
-     **/
+     * \sa rs_sig_begin() */
     RS_BLAKE2_SIG_MAGIC     = 0x72730137
 } rs_magic_number;
 
 
-/**
- * \brief Log severity levels.
+/** Log severity levels.
  *
  * These are the same as syslog, at least in glibc.
  *
  * \sa rs_trace_set_level()
- * \sa \ref api_trace
- */
+ * \sa \ref api_trace */
 typedef enum {
     RS_LOG_EMERG         = 0,   /**< System is unusable */
     RS_LOG_ALERT         = 1,   /**< Action must be taken immediately */
@@ -126,84 +115,77 @@ typedef enum {
 } rs_loglevel;
 
 
-/**
- * \typedef rs_trace_fn_t
- * \brief Callback to write out log messages.
+/** \typedef rs_trace_fn_t Callback to write out log messages.
+ *
  * \param level a syslog level.
+ *
  * \param msg message to be logged.
- * \sa \ref api_trace
- */
+ *
+ * \sa \ref api_trace */
 typedef void    rs_trace_fn_t(rs_loglevel level, char const *msg);
 
-/**
- * Set the least important message severity that will be output.
- * \sa \ref api_trace
- */
+/** Set the least important message severity that will be output.
+ *
+ * \sa \ref api_trace */
 void            rs_trace_set_level(rs_loglevel level);
 
 /** Set trace callback.
- * \sa \ref api_trace
- */
+ *
+ * \sa \ref api_trace */
 void            rs_trace_to(rs_trace_fn_t *);
 
-/** Default trace callback that writes to stderr.  Implements
- * ::rs_trace_fn_t, and may be passed to rs_trace_to().
- * \sa \ref api_trace
- */
+/** Default trace callback that writes to stderr.
+ *
+ * Implements ::rs_trace_fn_t, and may be passed to rs_trace_to().
+ *
+ * \sa \ref api_trace */
 void            rs_trace_stderr(rs_loglevel level, char const *msg);
 
-/** Check whether the library was compiled with debugging trace
+/** Check whether the library was compiled with debugging trace.
  *
  * \returns True if the library contains trace code; otherwise false.
+ *
  * If this returns false, then trying to turn trace on will achieve
  * nothing.
- * \sa \ref api_trace
- */
+ *
+ * \sa \ref api_trace */
 int             rs_supports_trace(void);
 
-/**
- * Convert \p from_len bytes at \p from_buf into a hex representation in
+/** Convert \p from_len bytes at \p from_buf into a hex representation in
  * \p to_buf, which must be twice as long plus one byte for the null
- * terminator.
- */
+ * terminator. */
 void     rs_hexify(char *to_buf, void const *from_buf, int from_len);
 
-/**
- * Decode a base64 buffer in place.
+/** Decode a base64 buffer in place.
  *
- * \returns The number of binary bytes.
- */
+ * \returns The number of binary bytes. */
 size_t rs_unbase64(char *s);
 
 
-/**
- * Encode a buffer as base64.
- */
+/** Encode a buffer as base64. */
 void rs_base64(unsigned char const *buf, int n, char *out);
 
 
-/**
- * \enum rs_result
- * \brief Return codes from nonblocking rsync operations.
- * \see rs_strerror()
- * \see api_callbacks
- */
+/** \enum rs_result Return codes from nonblocking rsync operations.
+ *
+ * \sa rs_strerror()
+ * \sa api_callbacks */
 typedef enum rs_result {
     RS_DONE =        0,    /**< Completed successfully. */
     RS_BLOCKED =    1,     /**< Blocked waiting for more data. */
 
-    /** The job is still running, and not yet finished or blocked.
-     * (This value should never be seen by the application.) */
-    RS_RUNNING  =       2,
+    RS_RUNNING  =       2, /**< The job is still running, and not yet finished
+			    * or blocked. (This value should never be seen by
+			    * the application.) */
 
     RS_TEST_SKIPPED =   77,     /**< Test neither passed or failed. */
 
     RS_IO_ERROR =    100,    /**< Error in file or network IO. */
     RS_SYNTAX_ERROR =   101,    /**< Command line syntax error. */
     RS_MEM_ERROR =    102,    /**< Out of memory. */
-    /** Unexpected end of input file, perhaps due to a truncated file
-     * or dropped network connection. */
-    RS_INPUT_ENDED =    103,
+    RS_INPUT_ENDED =    103,  /**< Unexpected end of input file, perhaps due
+			       * to a truncated file or dropped network
+			       * connection. */
     RS_BAD_MAGIC =      104,    /**< Bad magic number at start of
                                    stream.  Probably not a librsync
                                    file, or possibly the wrong kind of
@@ -217,20 +199,16 @@ typedef enum rs_result {
 } rs_result;
 
 
-/**
- * Return an English description of a ::rs_result value.
- */
+/** Return an English description of a ::rs_result value. */
 char const *rs_strerror(rs_result r);
 
 
-/**
- * \brief Performance statistics from a librsync encoding or decoding
+/** Performance statistics from a librsync encoding or decoding
  * operation.
  *
  * \sa api_stats
  * \sa rs_format_stats()
- * \sa rs_log_stats()
- */
+ * \sa rs_log_stats() */
 typedef struct rs_stats {
     char const     *op;     /**< Human-readable name of current
                              * operation.  For example, "delta". */
@@ -260,8 +238,7 @@ typedef struct rs_stats {
  * \brief MD4 message-digest accumulator.
  *
  * \sa rs_mdfour(), rs_mdfour_begin(), rs_mdfour_update(),
- * rs_mdfour_result()
- */
+ * rs_mdfour_result() */
 typedef struct rs_mdfour rs_mdfour_t;
 
 extern const int RS_MD4_SUM_LENGTH, RS_BLAKE2_SUM_LENGTH;
@@ -274,19 +251,18 @@ typedef unsigned char rs_strong_sum_t[RS_MAX_STRONG_SUM_LENGTH];
 void            rs_mdfour(unsigned char *out, void const *in, size_t);
 void            rs_mdfour_begin(/* @out@ */ rs_mdfour_t * md);
 
-/**
- * Feed some data into the MD4 accumulator.
+/** Feed some data into the MD4 accumulator.
  *
  * \param md  MD4 accumulator.
+ *
  * \param in_void Data to add.
- * \param n   Number of bytes fed in.
- */
+ *
+ * \param n   Number of bytes fed in. */
 void            rs_mdfour_update(rs_mdfour_t * md, void const *in_void,
                  size_t n);
 void rs_mdfour_result(rs_mdfour_t * md, unsigned char *out);
 
-/**
- * \brief Return a human-readable representation of statistics.
+/** Return a human-readable representation of statistics.
  *
  * The string is truncated if it does not fit.  100 characters should
  * be sufficient space.
@@ -294,17 +270,20 @@ void rs_mdfour_result(rs_mdfour_t * md, unsigned char *out);
  * \param stats Statistics from an encoding or decoding operation.
  *
  * \param buf Buffer to receive result.
+ *
  * \param size Size of buffer.
+ *
  * \return \p buf.
- * \see \ref api_stats
+ *
+ * \sa \ref api_stats
  */
 char *rs_format_stats(rs_stats_t const *stats, char *buf, size_t size);
 
 /**
  * Write statistics into the current log as text.
  *
- * \see \ref api_stats
- * \see \ref api_trace
+ * \sa \ref api_stats
+ * \sa \ref api_trace
  */
 int rs_log_stats(rs_stats_t const *stats);
 
@@ -331,7 +310,9 @@ void rs_sumset_dump(rs_signature_t const *);
  * On each call to ::rs_job_iter(), the caller can make available
  *
  *  - #avail_in bytes of input data at #next_in
+ *
  *  - #avail_out bytes of output space at #next_out
+ *
  *  - or some of both
  *
  * Buffers must be allocated and passed in by the caller.
@@ -357,15 +338,16 @@ void rs_sumset_dump(rs_signature_t const *);
  * \sa rs_job_iter()
  */
 struct rs_buffers_s {
-    /** \brief Next input byte.
+    /** Next input byte.
+     *
      * References a pointer which on entry should point to
      * the start of the data to be encoded.  Updated to point to the byte
      * after the last one consumed.
      **/
     char *next_in;
 
-    /**
-     * \brief Number of bytes available at next_in
+    /** Number of bytes available at next_in.
+     *
      * References the length of available input.  Updated to
      * be the number of unused data bytes, which will be zero if all the
      * input was consumed.  May be zero if there is no new input, but the
@@ -373,21 +355,18 @@ struct rs_buffers_s {
      */
     size_t avail_in;
 
-     /**
-      * \brief True if there is no more data after this.
-      */
+     /** True if there is no more data after this. */
     int eof_in;
 
-    /**
-     * \brief Next output byte should be put there
+    /** Next output byte should be put there.
+     *
      * References a pointer which on entry points to the
      * start of the output buffer.  Updated to point to the byte after the
      * last one filled.
      */
     char *next_out;
 
-    /**
-     * \brief Remaining free space at next_out
+    /** Remaining free space at next_out.
      *
      * References the size of available output buffer.
      * Updated to the size of unused output buffer.
@@ -396,7 +375,7 @@ struct rs_buffers_s {
 };
 
 /**
- * \see ::rs_buffers_s
+ * \sa ::rs_buffers_s
  */
 typedef struct rs_buffers_s rs_buffers_t;
 
@@ -404,8 +383,7 @@ typedef struct rs_buffers_s rs_buffers_t;
 #define RS_DEFAULT_BLOCK_LEN 2048
 
 
-/**
- * \brief Job of work to be done.
+/** Job of work to be done.
  *
  * Created by functions such as rs_sig_begin(), and then iterated
  * over by rs_job_iter().
@@ -413,14 +391,12 @@ typedef struct rs_buffers_s rs_buffers_t;
  * The contents are opaque to the application, and instances are always
  * allocated by the library.
  *
- * \see \ref api_streaming
- * \see rs_job
- */
+ * \sa \ref api_streaming
+ * \sa rs_job */
 typedef struct rs_job rs_job_t;
 
 
-/**
- * \brief Run a ::rs_job state machine until it blocks
+/** Run a ::rs_job state machine until it blocks
  * (::RS_BLOCKED), returns an error, or completes (::RS_DONE).
  *
  * \param job Description of job state.
@@ -434,37 +410,28 @@ typedef struct rs_job rs_job_t;
  * input buffer.  The final block checksum will run across whatever's
  * in there, without trying to accumulate anything else.
  *
- * \see \ref api_streaming.
- */
+ * \sa \ref api_streaming */
 rs_result       rs_job_iter(rs_job_t *job, rs_buffers_t *buffers);
 
-/**
- * Type of application-supplied function for rs_job_drive().
+/** Type of application-supplied function for rs_job_drive().
  *
- * \see \ref api_pull.
- **/
+ * \sa \ref api_pull */
 typedef rs_result rs_driven_cb(rs_job_t *job, rs_buffers_t *buf,
                                void *opaque);
 
-/**
- * Actively process a job, by making callbacks to fill and empty the
- * buffers until the job is done.
- */
+/** Actively process a job, by making callbacks to fill and empty the
+ * buffers until the job is done. */
 rs_result rs_job_drive(rs_job_t *job, rs_buffers_t *buf,
                        rs_driven_cb in_cb, void *in_opaque,
                        rs_driven_cb out_cb, void *out_opaque);
 
-/**
- * Return a pointer to the statistics in a job.
- */
+/** Return a pointer to the statistics in a job. */
 const rs_stats_t * rs_job_statistics(rs_job_t *job);
 
-/** Deallocate job state.
- */
+/** Deallocate job state. */
 rs_result       rs_job_free(rs_job_t *);
 
-/**
- * \brief Start generating a signature.
+/** Start generating a signature.
  *
  * \return A new rs_job_t into which the old file data can be passed.
  *
@@ -478,44 +445,36 @@ rs_result       rs_job_free(rs_job_t *);
  * many bytes, to make the signature shorter.  It's recommended you leave this
  * at zero to get the full strength.
  *
- * \sa rs_sig_file()
- */
+ * \sa rs_sig_file() */
 rs_job_t *rs_sig_begin(size_t new_block_len,
                        size_t strong_sum_len,
                        rs_magic_number sig_magic);
 
-/**
- * Prepare to compute a streaming delta.
+/** Prepare to compute a streaming delta.
  *
  * \todo Add a version of this that takes a ::rs_magic_number controlling the
- * delta format.
- **/
+ * delta format. */
 rs_job_t *rs_delta_begin(rs_signature_t *);
 
 
-/**
- * \brief Read a signature from a file into an ::rs_signature structure
+/** Read a signature from a file into an ::rs_signature structure
  * in memory.
  *
  * Once there, it can be used to generate a delta to a newer version of
  * the file.
  *
  * \note After loading the signatures, you must call
- * \ref rs_build_hash_table() before you can use them.
- */
+ * \ref rs_build_hash_table() before you can use them. */
 rs_job_t *rs_loadsig_begin(rs_signature_t **);
 
 
-/**
- * Call this after loading a signature to index it.
+/** Call this after loading a signature to index it.
  *
- * Use rs_free_sumset() to release it after use.
- */
+ * Use rs_free_sumset() to release it after use. */
 rs_result rs_build_hash_table(rs_signature_t* sums);
 
 
-/**
- * \brief Callback used to retrieve parts of the basis file.
+/** Callback used to retrieve parts of the basis file.
  *
  * \param pos Position where copying should begin.
  *
@@ -525,15 +484,13 @@ rs_result rs_build_hash_table(rs_signature_t* sums);
  *
  * \param buf On input, a buffer of at least \p *len bytes.  May be
  * updated to point to a buffer allocated by the callback if it
- * prefers.
- */
+ * prefers. */
 typedef rs_result rs_copy_cb(void *opaque, rs_long_t pos,
                              size_t *len, void **buf);
 
 
 
-/**
- * \brief Apply a \a delta to a \a basis file to recreate
+/** Apply a \a delta to a \a basis file to recreate
  * the \a new file.
  *
  * This gives you back a ::rs_job_t object, which can be cranked by
@@ -553,16 +510,14 @@ typedef rs_result rs_copy_cb(void *opaque, rs_long_t pos,
  * \todo Implement COPY commands.
  *
  * \sa rs_patch_file()
- * \sa \ref api_streaming
- */
+ * \sa \ref api_streaming */
 rs_job_t *rs_patch_begin(rs_copy_cb *copy_cb, void *copy_arg);
 
 
 #ifndef RSYNC_NO_STDIO_INTERFACE
 #include <stdio.h>
 
-/**
- * Buffer sizes for file IO.
+/** Buffer sizes for file IO.
  *
  * The default 0 means use the recommended buffer size for the
  * operation being performed, any other value will override the
@@ -571,8 +526,7 @@ rs_job_t *rs_patch_begin(rs_copy_cb *copy_cb, void *copy_arg);
 extern int rs_inbuflen, rs_outbuflen;
 
 
-/**
- * Generate the signature of a basis file, and write it out to
+/** Generate the signature of a basis file, and write it out to
  * another.
  *
  * \param old_file Stdio readable file whose signature will be generated.
@@ -588,44 +542,42 @@ extern int rs_inbuflen, rs_outbuflen;
  *
  * \param stats Optional pointer to receive statistics.
  *
- * \sa \ref api_whole
- */
+ * \sa \ref api_whole */
 rs_result rs_sig_file(FILE *old_file, FILE *sig_file,
                       size_t block_len, size_t strong_len,
               rs_magic_number sig_magic,
               rs_stats_t *stats);
 
-/**
- * Load signatures from a signature file into memory.  Return a
- * pointer to the newly allocated structure in \p sumset.
+/** Load signatures from a signature file into memory.
  *
- * \sa \ref api_whole
- */
+ * \param sig_file Readable stdio file from which the signature will be read.
+ *
+ * \param sumset on return points to the newly allocated structure.
+ *
+ * \param stats Optional pointer to receive statistics.
+ *
+ * \sa \ref api_whole */
 rs_result rs_loadsig_file(FILE *sig_file, rs_signature_t **sumset,
     rs_stats_t *stats);
 
-/**
- * ::rs_copy_cb that reads from a stdio file.
- **/
+/** ::rs_copy_cb that reads from a stdio file. */
 rs_result rs_file_copy_cb(void *arg, rs_long_t pos, size_t *len, void **buf);
 
 
-/**
- * Generate a delta between a signature and a new file, int a delta file.
- * \sa \ref api_whole
- **/
+/** Generate a delta between a signature and a new file into a delta file.
+ *
+ * \sa \ref api_whole */
 rs_result rs_delta_file(rs_signature_t *, FILE *new_file, FILE *delta_file, rs_stats_t *);
 
 
-/**
- * Apply a patch, relative to a basis, into a new file.
- * \sa \ref api_whole
- */
+/** Apply a patch, relative to a basis, into a new file.
+ *
+ * \sa \ref api_whole */
 rs_result rs_patch_file(FILE *basis_file, FILE *delta_file, FILE *new_file, rs_stats_t *);
 #endif /* ! RSYNC_NO_STDIO_INTERFACE */
 
 #ifdef __cplusplus
-}
+}                               /* extern "C" */
 #endif
 
 #endif /* ! _RSYNC_H */