Merge pull request #230 from dbaarda/dev/docs1

Fix #228 Improve GitHub and Doxygen Docs.

55 files changed, 202 insertions, 182 deletions

diff --git a/.gitattributes b/.gitattributes
index 82f5712..e24e7bc 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -1,6 +1,6 @@
 # Data files used for tests.
 *.data binary
-*.in binary
+*.input binary
 *.sig binary
 *.delta binary
 *.expect binary
diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml
index 23c50f6..5e1af9b 100644
--- a/.github/workflows/check.yml
+++ b/.github/workflows/check.yml
@@ -44,7 +44,7 @@ jobs:
       run: |
         if [ "$RUNNER_OS" == "Linux" ]; then
           sudo apt-get update -y
-          sudo apt-get install -y libpopt-dev libb2-dev doxygen ninja-build
+          sudo apt-get install -y libpopt-dev libb2-dev doxygen graphviz ninja-build
         elif [ "$RUNNER_OS" == "macOS" ]; then
           brew update
           brew install popt
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 2e29424..f5943db 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -218,7 +218,7 @@ if(DOXYGEN_FOUND)
     configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doc/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/doc/Doxyfile @ONLY)
     add_custom_target(doc
         ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doc/Doxyfile
-        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
         COMMENT "Generating API documentation with Doxygen" VERBATIM
     )
 endif(DOXYGEN_FOUND)
@@ -368,7 +368,7 @@ add_dependencies(check ${LAST_TARGET}
 enable_testing()
 
 # Create conf files
-configure_file(${CMAKE_CURRENT_SOURCE_DIR}/src/config.h.cmake ${CMAKE_CURRENT_BINARY_DIR}/src/config.h)
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/src/config.h.in ${CMAKE_CURRENT_BINARY_DIR}/src/config.h)
 
 # We need to be able to #include "file" from a few places,
 # * The original source dir
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 74a2ea3..6ddd6a1 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,4 +1,4 @@
-# Contributing to librsync {#page_contributing}
+# CONTRIBUTING
 
 Instructions and conventions for people wanting to work on librsync.  Please
 consider these guidelines even if you're doing your own fork.
diff --git a/NEWS.md b/NEWS.md
index b5613ac..1c72ab1 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,4 +1,4 @@
-# librsync NEWS
+# NEWS
 
 ## librsync 2.3.3
 
diff --git a/README.md b/README.md
index de95708..effe4bc 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# librsync
+# README
 
 http://librsync.sourcefrog.net/
 
@@ -6,10 +6,10 @@ http://librsync.sourcefrog.net/
 
 Copyright 1999-2016 Martin Pool and other contributors.
 
-librsync is distributed under the [GNU LGPL v2.1][LGPL]
-(see COPYING), which basically
-means that you can dynamically link librsync into non-GPL programs, but you
-must redistribute the librsync source, with any modifications you have made.
+librsync is distributed under the [GNU LGPL v2.1][LGPL] (see COPYING), which
+basically means that you can dynamically link librsync into non-GPL programs,
+but you must redistribute the librsync source, with any modifications you have
+made.
 
 [LGPL]: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html
 
@@ -21,63 +21,60 @@ released under the [CC0 public domain dedication][CC0].
 
 ## Introduction
 
-librsync is a library for calculating and applying network deltas,
-with an interface designed to ease integration into diverse
-network applications.
+librsync is a library for calculating and applying network deltas, with an
+interface designed to ease integration into diverse network applications.
 
-librsync encapsulates the core algorithms of the rsync protocol, which
-help with efficient calculation of the differences between two files.
-The rsync algorithm is different from most differencing algorithms
-because it does not require the presence of the two files to calculate
-the delta.  Instead, it requires a set of checksums of each block of
-one file, which together form a signature for that file.  Blocks at
-any in the other file which have the same checksum are likely to be
-identical, and whatever remains is the difference.
+librsync encapsulates the core algorithms of the rsync protocol, which help
+with efficient calculation of the differences between two files. The rsync
+algorithm is different from most differencing algorithms because it does not
+require the presence of the two files to calculate the delta.  Instead, it
+requires a set of checksums of each block of one file, which together form a
+signature for that file.  Blocks at any in the other file which have the same
+checksum are likely to be identical, and whatever remains is the difference.
 
-This algorithm transfers the differences between two files without
-needing both files on the same system.
+This algorithm transfers the differences between two files without needing
+both files on the same system.
 
-librsync is for building other programs that transfer files as efficiently
-as rsync. You can use librsync in a program you write to do backups,
-distribute binary patches to programs, or sync directories to a server
-or between peers.
+librsync is for building other programs that transfer files as efficiently as
+rsync. You can use librsync in a program you write to do backups, distribute
+binary patches to programs, or sync directories to a server or between peers.
 
 This tree also produces the \ref page_rdiff that exposes the key operations of
 librsync: generating file signatures, generating the delta from a signature to
 a new file, and applying the delta to regenerate the new file given the old
 file.
 
-librsync was originally written for the rproxy experiment in
-delta-compression for HTTP.
-librsync is used by: [Dropbox](https://dropbox.com/),
+librsync was originally written for the rproxy experiment in delta-compression
+for HTTP. librsync is used by: [Dropbox](https://dropbox.com/),
 [rdiff-backup](http://www.nongnu.org/rdiff-backup/),
-[Duplicity](http://www.nongnu.org/duplicity/), and others.
-(If you would like to be listed here, let me know.)
+[Duplicity](http://www.nongnu.org/duplicity/), and others. (If you would like
+to be listed here, let me know.)
 
 ### What librsync is not
 
 1. librsync does not implement the rsync wire protocol. If you want to talk to
-an rsync server to transfer files you'll need to shell out to `rsync`.
-You cannot make use of librsync to talk to an rsync server.
+an rsync server to transfer files you'll need to shell out to `rsync`. You
+cannot make use of librsync to talk to an rsync server.
 
 2. librsync does not deal with file metadata or structure, such as filenames,
-permissions, or directories. To this library, a file is just a stream of bytes.
-Higher-level tools can deal with such issues in a way appropriate to their
-users.
- 
-3. librsync also does not include any network functions for talking to SSH
-or any other server. To access a remote filesystem, you need to provide
-your own code or make use of some other virtual filesystem layer.
+permissions, or directories. To this library, a file is just a stream of
+bytes. Higher-level tools can deal with such issues in a way appropriate to
+their users.
+
+3. librsync also does not include any network functions for talking to SSH or
+any other server. To access a remote filesystem, you need to provide your own
+code or make use of some other virtual filesystem layer.
 
 
 ## More information
 
 * \ref page_downloads
-* \ref versioning
+* \ref page_versioning
 * \ref page_install
 * \ref page_rdiff
-* \ref page_api
+* \ref page_librsync
 * \ref page_formats
 * \ref page_support
-* \ref page_contributing
-* \ref NEWS.md
+* [CONTRIBUTING](CONTRIBUTING.md)
+* [NEWS](NEWS.md)
+* [TODO](TODO.md)
diff --git a/TODO.md b/TODO.md
index e2ac4bb..1106bb0 100644
--- a/TODO.md
+++ b/TODO.md
@@ -1,4 +1,4 @@
-# librsync TODO
+# TODO
 
 * We have a few functions to do with reading a netint, stashing
   it somewhere, then moving into a different state.  Is it worth
diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
index 1ce6651..5d8fc5d 100644
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@@ -58,7 +58,7 @@ PROJECT_LOGO           =
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = .
+OUTPUT_DIRECTORY       = @CMAKE_CURRENT_BINARY_DIR@
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
 # directories (in 2 levels) under the output directory of each output format and
@@ -1735,7 +1735,7 @@ COMPACT_LATEX          = YES
 # The default value is: a4.
 # This tag requires that the tag GENERATE_LATEX is set to YES.
 
-PAPER_TYPE             = a4wide
+PAPER_TYPE             = a4
 
 # The EXTRA_PACKAGES tag can be used to specify one or more LaTeX package names
 # that should be included in the LaTeX output. The package can be specified just
@@ -2243,7 +2243,7 @@ HIDE_UNDOC_RELATIONS   = YES
 # set to NO
 # The default value is: YES.
 
-HAVE_DOT               = NO
+HAVE_DOT               = YES
 
 # The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed
 # to run in parallel. When set to 0 doxygen will base this on the number of
@@ -2405,7 +2405,7 @@ DIRECTORY_GRAPH        = YES
 # The default value is: png.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOT_IMAGE_FORMAT       = png
+DOT_IMAGE_FORMAT       = svg
 
 # If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to
 # enable generation of interactive SVG images that allow zooming and panning.
diff --git a/doc/format.md b/doc/formats.md
index eb505c1..eb505c1 100644
--- a/doc/format.md
+++ b/doc/formats.md
diff --git a/doc/install.md b/doc/install.md
index 75709b0..7e9d89a 100644
--- a/doc/install.md
+++ b/doc/install.md
@@ -1,4 +1,4 @@
-# Installing librsync {#page_install}
+# Installing {#page_install}
 
 ## Requirements
 
diff --git a/doc/librsync.md b/doc/librsync.md
index fa2007a..dcbbc2c 100644
--- a/doc/librsync.md
+++ b/doc/librsync.md
@@ -1,4 +1,4 @@
-# API Overview {#page_api}
+# librsync library {#page_librsync}
 
 The library supports four basic operations:
 
@@ -24,8 +24,8 @@ Other documentation pages:
 - \ref api_trace - aid debugging by showing messages about librsync's state.
 - \ref api_callbacks
 - \ref api_stats
-- \ref api_utility
-- \ref versioning
+- \ref api_utilities
+- \ref page_versioning
 
 The public interface to librsync is librsync.h, and other headers are internal.
 
diff --git a/doc/pull.md b/doc/pull.md
index a5ff14c..7ffe69a 100644
--- a/doc/pull.md
+++ b/doc/pull.md
@@ -1,4 +1,4 @@
-# Callback API {#api_pull}
+# Pull API {#api_pull}
 
 As an alternative to \ref api_streaming, librsync provides a "pull-mode"
 callback interface where it will repeatedly call application-provided
diff --git a/doc/trace.md b/doc/trace.md
index b622739..81df69f 100644
--- a/doc/trace.md
+++ b/doc/trace.md
@@ -1,4 +1,4 @@
-# Debugging trace and error logging {#api_trace}
+# Trace output {#api_trace}
  
 librsync can output trace or log messages as it proceeds.
 Error
diff --git a/doc/utilities.md b/doc/utilities.md
index f7d395e..e444234 100644
--- a/doc/utilities.md
+++ b/doc/utilities.md
@@ -1,4 +1,4 @@
-# Utility functions {#api_utility}
+# Utility functions {#api_utilities}
 
 Some additional functions are used internally and also exposed in the
 API:
diff --git a/doc/versioning.md b/doc/versioning.md
index c9d3b0c..267911b 100644
--- a/doc/versioning.md
+++ b/doc/versioning.md
@@ -1,4 +1,4 @@
-# Versioning {#versioning}
+# Versioning {#page_versioning}
 
 librsync uses the [SemVer] approach to versioning: the major version number
 changes when the API changes in an incompatible way, the minor version
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/config.h.cmake b/src/config.h.in
index d5b6392..6d4523a 100644
--- a/src/config.h.cmake
+++ b/src/config.h.in
@@ -1,4 +1,4 @@
-/* config.h.  Generated from config.h.cmake by cmake.  */
+/* config.h.  Generated from config.h.in by cmake.  */
 
 /* Define if building universal (internal helper macro) */
 #cmakedefine AC_APPLE_UNIVERSAL_BUILD
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/librsync.h b/src/librsync.h
index eb758da..83fb27d 100644
--- a/src/librsync.h
+++ b/src/librsync.h
@@ -43,7 +43,7 @@ extern "C" {
 
 /** Library version string.
  *
- * \sa \ref versioning */
+ * \sa \ref page_versioning */
 LIBRSYNC_EXPORT extern char const rs_librsync_version[];
 
 typedef uint8_t rs_byte_t;
@@ -482,6 +482,9 @@ LIBRSYNC_EXPORT rs_result rs_build_hash_table(rs_signature_t *sums);
 
 /** Callback used to retrieve parts of the basis file.
  *
+ * \param opaque The opaque object to execute the callback with. Often the file
+ * to read from.
+ *
  * \param pos Position where copying should begin.
  *
  * \param len On input, the amount of data that should be retrieved. Updated to
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);
 
diff --git a/tests/changes.input/01.in b/tests/changes.input/01.input
index e6e3285..e6e3285 100644
--- a/tests/changes.input/01.in
+++ b/tests/changes.input/01.input
diff --git a/tests/changes.input/02.in b/tests/changes.input/02.input
index 6028817..6028817 100644
--- a/tests/changes.input/02.in
+++ b/tests/changes.input/02.input
diff --git a/tests/changes.input/03.in b/tests/changes.input/03.input
index 281f004..281f004 100644
--- a/tests/changes.input/03.in
+++ b/tests/changes.input/03.input
diff --git a/tests/changes.input/04.in b/tests/changes.input/04.input
index 11264ae..11264ae 100644
--- a/tests/changes.input/04.in
+++ b/tests/changes.input/04.input
diff --git a/tests/changes.input/05.in b/tests/changes.input/05.input
index c6d6974..c6d6974 100644
--- a/tests/changes.input/05.in
+++ b/tests/changes.input/05.input
diff --git a/tests/changes.input/06.in b/tests/changes.input/06.input
index e69de29..e69de29 100644
--- a/tests/changes.input/06.in
+++ b/tests/changes.input/06.input
diff --git a/tests/changes.input/07.in b/tests/changes.input/07.input
index ce01362..ce01362 100644
--- a/tests/changes.input/07.in
+++ b/tests/changes.input/07.input
diff --git a/tests/changes.test b/tests/changes.test
index 81acdfe..e9be0a0 100755
--- a/tests/changes.test
+++ b/tests/changes.test
@@ -1,21 +1,21 @@
 #! /bin/sh -e
 
 # librsync -- the library for network deltas
-# 
+#
 # Copyright (C) 2001, 2014 by Martin Pool <mbp@sourcefrog.net>
 
 # changes.test: Test converting in both directions between each pair of files.
- 
+
 # This program is free software; you can redistribute it and/or
 # modify it under the terms of the GNU Lesser General Public License
 # as published by the Free Software Foundation; either version 2.1 of
 # the License, or (at your option) any later version.
-# 
+#
 # This program is distributed in the hope that it will be useful, but
 # WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 # Lesser General Public License for more details.
-# 
+#
 # You should have received a copy of the GNU Lesser General Public
 # License along with this program; if not, write to the Free Software
 # Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
@@ -28,13 +28,13 @@ inputdir=$srcdir/changes.input
 
 for buf in $bufsizes
 do
-    old=$inputdir/01.in
-    for new in $inputdir/*.in
+    old=$inputdir/01.input
+    for new in $inputdir/*.input
     do
 	for hashopt in '' -Hmd4 -Hblake2
 	do
 	    triple_test $buf $old $new $hashopt
-	    triple_test $buf $new $old $hashopt 
+	    triple_test $buf $new $old $hashopt
 	done
     done
 done
diff --git a/tests/signature.input/01.in b/tests/signature.input/01.input
index c4792dd..c4792dd 100644
--- a/tests/signature.input/01.in
+++ b/tests/signature.input/01.input
diff --git a/tests/signature.test b/tests/signature.test
index ae8c967..0a9c576 100755
--- a/tests/signature.test
+++ b/tests/signature.test
@@ -31,9 +31,9 @@ new=$tmpdir/signature
 for rollfunc in rollsum rabinkarp; do
   for hashfunc in md4 blake2; do
     for stronglen in 0 -1 8; do
-      for input in "$srcdir/signature.input"/*.in; do
+      for input in "$srcdir/signature.input"/*.input; do
         for inbuf in $bufsizes; do
-          expect=`echo $input | sed -e "s/.in\$/-R${rollfunc}-H${hashfunc}-S${stronglen}.sig/"`
+          expect=`echo $input | sed -e "s/.input\$/-R${rollfunc}-H${hashfunc}-S${stronglen}.sig/"`
           run_test ${RDIFF} -R$rollfunc -H$hashfunc -S$stronglen -I$inbuf -f signature "$input" "$new"
           check_compare "$expect" "$new"
 	done
diff --git a/tests/triple.input/copying.in b/tests/triple.input/copying.input
index c4792dd..c4792dd 100644
--- a/tests/triple.input/copying.in
+++ b/tests/triple.input/copying.input
diff --git a/tests/triple.input/half.in b/tests/triple.input/half.input
index 06ed63b..06ed63b 100644
--- a/tests/triple.input/half.in
+++ b/tests/triple.input/half.input
diff --git a/tests/triple.input/hello.in b/tests/triple.input/hello.input
index 10ddd6d..10ddd6d 100644
--- a/tests/triple.input/hello.in
+++ b/tests/triple.input/hello.input
diff --git a/tests/triple.input/zero.in b/tests/triple.input/zero.input
index e69de29..e69de29 100644
--- a/tests/triple.input/zero.in
+++ b/tests/triple.input/zero.input
diff --git a/tests/triple.test b/tests/triple.test
index f2f77aa..c2aa4e1 100755
--- a/tests/triple.test
+++ b/tests/triple.test
@@ -25,9 +25,9 @@ inputdir=$srcdir/triple.input
 
 for buf in $bufsizes
 do
-    for old in $inputdir/*.in
+    for old in $inputdir/*.input
     do
-        for new in $inputdir/*.in
+        for new in $inputdir/*.input
         do
             for hashopt in -Hmd4 -Hblake2
             do