Add doxygen `\file` docs to all headers and state engine files.

Move doxygen docs from `*.c` files to their corresponding `*.h` files if there
is one. Remove any "private" or "internal" markers from docs. It's already
clear the librsync.h is the only public interface, but the rest of the docs
are useful for understanding the code so we still want to generate them.

23 files changed, 130 insertions, 110 deletions

diff --git a/src/buf.c b/src/buf.c
index 8087297..1e7a69d 100644
--- a/src/buf.c
+++ b/src/buf.c
@@ -23,19 +23,6 @@
                                | Pick a window, Jimmy, you're leaving.
                                */
 
-/** \file buf.c
- * Buffers that map between stdio file streams and librsync streams.
- *
- * As the stream consumes input and produces output, it is refilled from
- * appropriate input and output FILEs. A dynamically allocated buffer of
- * configurable size is used as an intermediary.
- *
- * \todo Perhaps be more efficient by filling the buffer on every call even if
- * not yet completely empty. Check that it's really our buffer, and shuffle
- * remaining data down to the front.
- *
- * \todo Perhaps expose a routine for shuffling the buffers. */
-
 #include <assert.h>
 #include <stdlib.h>
 #include <errno.h>
diff --git a/src/buf.h b/src/buf.h
index 098de03..8019fd7 100644
--- a/src/buf.h
+++ b/src/buf.h
@@ -18,6 +18,19 @@
  * License along with this program; if not, write to the Free Software
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
+
+/** \file buf.h
+ * Buffers that map between stdio file streams and librsync streams.
+ *
+ * As the stream consumes input and produces output, it is refilled from
+ * appropriate input and output FILEs. A dynamically allocated buffer of
+ * configurable size is used as an intermediary.
+ *
+ * \todo Perhaps be more efficient by filling the buffer on every call even if
+ * not yet completely empty. Check that it's really our buffer, and shuffle
+ * remaining data down to the front.
+ *
+ * \todo Perhaps expose a routine for shuffling the buffers. */
 #ifndef BUF_H
 #  define BUF_H
 
diff --git a/src/checksum.h b/src/checksum.h
index e2162b0..46ed9a4 100644
--- a/src/checksum.h
+++ b/src/checksum.h
@@ -18,6 +18,9 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
+
+/** \file checksum.h
+ * Abstract wrappers around different weaksum and strongsum implementations. */
 #ifndef CHECKSUM_H
 #  define CHECKSUM_H
 
diff --git a/src/emit.c b/src/emit.c
index 0786957..9423fc0 100644
--- a/src/emit.c
+++ b/src/emit.c
@@ -19,12 +19,6 @@
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
 
-/** \file emit.c
- * encoding output routines.
- *
- * \todo Pluggable encoding formats: gdiff-style, rsync 24, ed (text), Delta
- * HTTP. */
-
 #include <assert.h>
 #include "librsync.h"
 #include "emit.h"
@@ -33,14 +27,12 @@
 #include "prototab.h"
 #include "trace.h"
 
-/** Write the magic for the start of a delta. */
 void rs_emit_delta_header(rs_job_t *job)
 {
     rs_trace("emit DELTA magic");
     rs_squirt_n4(job, RS_DELTA_MAGIC);
 }
 
-/** Write a LITERAL command. */
 void rs_emit_literal_cmd(rs_job_t *job, int len)
 {
     int cmd;
@@ -70,10 +62,6 @@ void rs_emit_literal_cmd(rs_job_t *job, int len)
     job->stats.lit_cmdbytes += 1 + param_len;
 }
 
-/** Write a COPY command for given offset and length.
- *
- * There is a choice of variable-length encodings, depending on the size of
- * representation for the parameters. */
 void rs_emit_copy_cmd(rs_job_t *job, rs_long_t where, rs_long_t len)
 {
     int cmd;
@@ -113,7 +101,6 @@ void rs_emit_copy_cmd(rs_job_t *job, rs_long_t where, rs_long_t len)
     stats->copy_cmdbytes += 1 + where_bytes + len_bytes;
 }
 
-/** Write an END command. */
 void rs_emit_end_cmd(rs_job_t *job)
 {
     int cmd = RS_OP_END;
diff --git a/src/emit.h b/src/emit.h
index 53dc81e..85be65f 100644
--- a/src/emit.h
+++ b/src/emit.h
@@ -20,15 +20,28 @@
  */
 
 /** \file emit.h
- * How to emit commands to the client. */
+ * encoding output routines.
+ *
+ * \todo Pluggable encoding formats: gdiff-style, rsync 24, ed (text), Delta
+ * HTTP. */
 #ifndef EMIT_H
 #  define EMIT_H
 
 #  include "librsync.h"
 
+/** Write the magic for the start of a delta. */
 void rs_emit_delta_header(rs_job_t *);
+
+/** Write a LITERAL command. */
 void rs_emit_literal_cmd(rs_job_t *, int len);
-void rs_emit_end_cmd(rs_job_t *);
+
+/** Write a COPY command for given offset and length.
+ *
+ * There is a choice of variable-length encodings, depending on the size of
+ * representation for the parameters. */
 void rs_emit_copy_cmd(rs_job_t *job, rs_long_t where, rs_long_t len);
 
+/** Write an END command. */
+void rs_emit_end_cmd(rs_job_t *);
+
 #endif                          /* !EMIT_H */
diff --git a/src/isprefix.c b/src/isprefix.c
index e0fd2b0..aa879e7 100644
--- a/src/isprefix.c
+++ b/src/isprefix.c
@@ -20,7 +20,6 @@
 
 #include "isprefix.h"
 
-/** Return true if TIP is a prefix of ICEBERG. */
 int isprefix(char const *tip, char const *iceberg)
 {
     while (*tip) {
diff --git a/src/isprefix.h b/src/isprefix.h
index 287a23a..9ad2499 100644
--- a/src/isprefix.h
+++ b/src/isprefix.h
@@ -17,6 +17,9 @@
  * License along with this program; if not, write to the Free Software
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
+
+/** \file isprefix.h
+ * String prefix text function. */
 #ifndef ISPREFIX_H
 #  define ISPREFIX_H
 
diff --git a/src/job.c b/src/job.c
index 41afd22..84b72f4 100644
--- a/src/job.c
+++ b/src/job.c
@@ -25,14 +25,6 @@
                                | sheltering.
                                */
 
-/** \file job.c
- * Generic state-machine interface.
- *
- * The point of this is that we need to be able to suspend and resume
- * processing at any point at which the buffers may block.
- *
- * \sa \ref api_streaming \sa rs_job_iter() \sa ::rs_job */
-
 #include <assert.h>
 #include <stdlib.h>
 #include <time.h>
diff --git a/src/job.h b/src/job.h
index e309273..e5c8ba5 100644
--- a/src/job.h
+++ b/src/job.h
@@ -18,6 +18,14 @@
  * License along with this program; if not, write to the Free Software
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
+
+/** \file job.h
+ * Generic state-machine interface.
+ *
+ * The point of this is that we need to be able to suspend and resume
+ * processing at any point at which the buffers may block.
+ *
+ * \sa \ref api_streaming \sa rs_job_iter() \sa ::rs_job */
 #ifndef JOB_H
 #  define JOB_H
 
diff --git a/src/mdfour.c b/src/mdfour.c
index 1e9c39e..a32728b 100644
--- a/src/mdfour.c
+++ b/src/mdfour.c
@@ -21,24 +21,6 @@
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
 
-/** \file mdfour.c
- * MD4 message digest algorithm.
- *
- * \todo Perhaps use the MD4 routine from OpenSSL if it's installed. It's
- * probably not worth the trouble.
- *
- * This was originally written by Andrew Tridgell for use in Samba. It was then
- * modified by;
- *
- * 2002-06-xx: Robert Weber <robert.weber@Colorado.edu> optimisations and fixed
- * >512M support.
- *
- * 2002-06-27: Donovan Baarda <abo@minkirri.apana.org.au> further optimisations
- * and cleanups.
- *
- * 2004-09-09: Simon Law <sfllaw@debian.org> handle little-endian machines that
- * can't do unaligned access (e.g. ia64, pa-risc). */
-
 #include <stdint.h>
 #include <string.h>
 #include "librsync.h"
diff --git a/src/mdfour.h b/src/mdfour.h
index a8e35b1..2c11d73 100644
--- a/src/mdfour.h
+++ b/src/mdfour.h
@@ -19,12 +19,30 @@
  * License along with this program; if not, write to the Free Software
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
+
+/** \file mdfour.h
+ * MD4 message digest algorithm.
+ *
+ * \todo Perhaps use the MD4 routine from OpenSSL if it's installed. It's
+ * probably not worth the trouble.
+ *
+ * This was originally written by Andrew Tridgell for use in Samba. It was then
+ * modified by;
+ *
+ * 2002-06-xx: Robert Weber <robert.weber@Colorado.edu> optimisations and fixed
+ * >512M support.
+ *
+ * 2002-06-27: Donovan Baarda <abo@minkirri.apana.org.au> further optimisations
+ * and cleanups.
+ *
+ * 2004-09-09: Simon Law <sfllaw@debian.org> handle little-endian machines that
+ * can't do unaligned access (e.g. ia64, pa-risc). */
 #ifndef MDFOUR_H
 #  define MDFOUR_H
 
 #  include <stdint.h>
 
-/** \private Internal state while computing an MD4 hash. */
+/** The rs_mdfour state type. */
 struct rs_mdfour {
     unsigned int A, B, C, D;
 #  ifdef UINT64_MAX
diff --git a/src/netint.c b/src/netint.c
index af28d89..e533b19 100644
--- a/src/netint.c
+++ b/src/netint.c
@@ -27,17 +27,6 @@
                              |        -- Sun Microsystems
                              */
 
-/** \file netint.c
- * Network-byte-order output to the tube.
- *
- * All the `suck' routines return a result code. The most common values are
- * RS_DONE if they have enough data, or RS_BLOCKED if there is not enough input
- * to proceed.
- *
- * The `squirt` routines also return a result code which in theory could be
- * RS_BLOCKED if there is not enough output space to proceed, but in practice
- * is always RS_DONE. */
-
 #include <assert.h>
 #include "librsync.h"
 #include "netint.h"
@@ -45,20 +34,12 @@
 
 #define RS_MAX_INT_BYTES 8
 
-/** Write a single byte to a stream output. */
 rs_result rs_squirt_byte(rs_job_t *job, rs_byte_t val)
 {
     rs_tube_write(job, &val, 1);
     return RS_DONE;
 }
 
-/** Write a variable-length integer to a stream.
- *
- * \param job - Job of data.
- *
- * \param val - Value to write out.
- *
- * \param len - Length of integer, in bytes. */
 rs_result rs_squirt_netint(rs_job_t *job, rs_long_t val, int len)
 {
     rs_byte_t buf[RS_MAX_INT_BYTES];
diff --git a/src/netint.h b/src/netint.h
index 90bd508..a89021b 100644
--- a/src/netint.h
+++ b/src/netint.h
@@ -19,17 +19,40 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
+
+/** \file netint.h
+ * Network-byte-order output to the tube.
+ *
+ * All the `suck' routines return a result code. The most common values are
+ * RS_DONE if they have enough data, or RS_BLOCKED if there is not enough input
+ * to proceed.
+ *
+ * The `squirt` routines also return a result code which in theory could be
+ * RS_BLOCKED if there is not enough output space to proceed, but in practice
+ * is always RS_DONE. */
 #ifndef NETINT_H
 #  define NETINT_H
 
 #  include "librsync.h"
 
+/** Write a single byte to a stream output. */
 rs_result rs_squirt_byte(rs_job_t *job, rs_byte_t val);
+
+/** Write a variable-length integer to a stream.
+ *
+ * \param job - Job of data.
+ *
+ * \param val - Value to write out.
+ *
+ * \param len - Length of integer, in bytes. */
 rs_result rs_squirt_netint(rs_job_t *job, rs_long_t val, int len);
+
 rs_result rs_squirt_n4(rs_job_t *job, int val);
 
 rs_result rs_suck_byte(rs_job_t *job, rs_byte_t *val);
+
 rs_result rs_suck_netint(rs_job_t *job, rs_long_t *val, int len);
+
 rs_result rs_suck_n4(rs_job_t *job, int *val);
 
 int rs_int_len(rs_long_t val);
diff --git a/src/patch.c b/src/patch.c
index d4e2f8f..5fae2bb 100644
--- a/src/patch.c
+++ b/src/patch.c
@@ -23,6 +23,9 @@
                                | This is Tranquility Base.
                                */
 
+/** \file patch.c
+ * Apply a delta to an old file to generate a new file. */
+
 #include <assert.h>
 #include <stdlib.h>
 #include <string.h>
diff --git a/src/prototab.c b/src/prototab.c
index 9d1e4b1..92a4256 100644
--- a/src/prototab.c
+++ b/src/prototab.c
@@ -20,13 +20,6 @@
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
 
-/** \file prototab.c
- * Delta file commands.
- *
- * This file defines an array mapping command IDs to the operation kind,
- * implied literal value, and length of the first and second parameters. The
- * implied value is only used if the first parameter length is zero. */
-
 #include "command.h"
 #include "prototab.h"
 
diff --git a/src/prototab.h b/src/prototab.h
index 0270700..f430e56 100644
--- a/src/prototab.h
+++ b/src/prototab.h
@@ -29,7 +29,11 @@
 				     */
 
 /** \file prototab.h
- * Delta file commands. */
+ * Delta file commands.
+ *
+ * This file defines an array mapping command IDs to the operation kind,
+ * implied literal value, and length of the first and second parameters. The
+ * implied value is only used if the first parameter length is zero. */
 #ifndef PROTOTAB_H
 #  define PROTOTAB_H
 
diff --git a/src/rabinkarp.h b/src/rabinkarp.h
index b97db86..dfd87f1 100644
--- a/src/rabinkarp.h
+++ b/src/rabinkarp.h
@@ -18,6 +18,9 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
+
+/** \file rabinkarp.h
+ * The rabinkarp class implementation of the RabinKarp rollsum. */
 #ifndef RABINKARP_H
 #  define RABINKARP_H
 
@@ -50,7 +53,7 @@
 #  define RABINKARP_ADJ 0x08104224U
 
 /** The rabinkarp_t state type. */
-typedef struct _rabinkarp {
+typedef struct rabinkarp {
     size_t count;               /**< Count of bytes included in sum. */
     uint32_t hash;              /**< The accumulated hash value. */
     uint32_t mult;              /**< The value of RABINKARP_MULT^count. */
diff --git a/src/rollsum.h b/src/rollsum.h
index 07c30cc..9f33dd0 100644
--- a/src/rollsum.h
+++ b/src/rollsum.h
@@ -19,6 +19,9 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
+
+/** \file rollsum.h
+ * The Rollsum class implementation of the original rsync rollsum. */
 #ifndef ROLLSUM_H
 #  define ROLLSUM_H
 
@@ -29,11 +32,11 @@
    algorithm: tridge suggests a prime number. */
 #  define ROLLSUM_CHAR_OFFSET 31
 
-/** The Rollsum struct type \private. */
-typedef struct _Rollsum {
-    size_t count;               /* count of bytes included in sum */
-    uint_fast16_t s1;           /* s1 part of sum */
-    uint_fast16_t s2;           /* s2 part of sum */
+/** The Rollsum state type. */
+typedef struct Rollsum {
+    size_t count;               /**< count of bytes included in sum */
+    uint_fast16_t s1;           /**< s1 part of sum */
+    uint_fast16_t s2;           /**< s2 part of sum */
 } Rollsum;
 
 void RollsumUpdate(Rollsum *sum, const unsigned char *buf, size_t len);
diff --git a/src/sumset.h b/src/sumset.h
index 3ac2a5c..3ae1fcb 100644
--- a/src/sumset.h
+++ b/src/sumset.h
@@ -19,6 +19,9 @@
  * License along with this program; if not, write to the Free Software
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
+
+/** \file sumset.h
+ * The rs_signature class implementation of a file signature. */
 #ifndef SUMSET_H
 #  define SUMSET_H
 
diff --git a/src/trace.c b/src/trace.c
index 53e48b2..426e1be 100644
--- a/src/trace.c
+++ b/src/trace.c
@@ -26,12 +26,6 @@
                                       | There are lumps in it.
                                       */
 
-/** \file trace.c
- * logging and debugging output.
- *
- * \todo Have a bit set in the log level that says not to include the function
- * name. */
-
 #include <stdio.h>
 #include <stdarg.h>
 #include "config.h"
diff --git a/src/util.h b/src/util.h
index a1c333b..704458b 100644
--- a/src/util.h
+++ b/src/util.h
@@ -19,6 +19,9 @@
  * License along with this program; if not, write to the Free Software
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
+
+/** \file util.h
+ * Misc utility functions used by librsync. */
 #ifndef UTIL_H
 #  define UTIL_H
 
diff --git a/src/whole.c b/src/whole.c
index ff58155..04777f8 100644
--- a/src/whole.c
+++ b/src/whole.c
@@ -39,21 +39,6 @@
 /** Whole file IO buffer sizes. */
 LIBRSYNC_EXPORT int rs_inbuflen = 0, rs_outbuflen = 0;
 
-/** Run a job continuously, with input to/from the two specified files.
- *
- * The job should already be set up, and must be freed by the caller after
- * return. If rs_inbuflen or rs_outbuflen are set, they will override the
- * inbuflen and outbuflen arguments.
- *
- * \param in_file - input file, or NULL if there is no input.
- *
- * \param out_file - output file, or NULL if there is no output.
- *
- * \param inbuflen - recommended input buffer size to use.
- *
- * \param outbuflen - recommended output buffer size to use.
- *
- * \return RS_DONE if the job completed, or otherwise an error result. */
 rs_result rs_whole_run(rs_job_t *job, FILE *in_file, FILE *out_file,
                        int inbuflen, int outbuflen)
 {
diff --git a/src/whole.h b/src/whole.h
index 98e082c..e872bc1 100644
--- a/src/whole.h
+++ b/src/whole.h
@@ -18,12 +18,32 @@
  * License along with this program; if not, write to the Free Software
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
+
+/** \file whole.h
+ * Whole-file API driver functions. */
 #ifndef WHOLE_H
 #  define WHOLE_H
 
 #  include <stdio.h>
 #  include "librsync.h"
 
+/** Run a job continuously, with input to/from the two specified files.
+ *
+ * The job should already be set up, and must be freed by the caller after
+ * return. If rs_inbuflen or rs_outbuflen are set, they will override the
+ * inbuflen and outbuflen arguments.
+ *
+ * \param job - the job instance to run.
+ *
+ * \param in_file - input file, or NULL if there is no input.
+ *
+ * \param out_file - output file, or NULL if there is no output.
+ *
+ * \param inbuflen - recommended input buffer size to use.
+ *
+ * \param outbuflen - recommended output buffer size to use.
+ *
+ * \return RS_DONE if the job completed, or otherwise an error result. */
 rs_result rs_whole_run(rs_job_t *job, FILE *in_file, FILE *out_file,
                        int inbuflen, int outbuflen);