Minor tidyups to comments in preparation for autoformatting.

27 files changed, 84 insertions, 123 deletions

diff --git a/src/base64.c b/src/base64.c
index 88e1b61..087af5e 100644
--- a/src/base64.c
+++ b/src/base64.c
@@ -1,25 +1,24 @@
 /*= -*- c-basic-offset: 4; indent-tabs-mode: nil; -*-
  *
  * librsync -- the library for network deltas
- * 
+ *
  * Copyright (C) 2000 by Martin Pool <mbp@sourcefrog.net>
- * 
+ *
  * 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.
  */
 
-
 #include "config.h"
 
 #include <string.h>
@@ -28,11 +27,9 @@
 
 #include "librsync.h"
 
-/*
- * Decode a base64 string in-place - simple and slow algorithm
- * 
- * See RFC1521 for the specification of base64.
- */
+/** Decode a base64 string in-place - simple and slow algorithm.
+ *
+ * See RFC1521 for the specification of base64. */
 size_t rs_unbase64(char *s)
 {
     char const *b64 =
@@ -64,11 +61,8 @@ size_t rs_unbase64(char *s)
     return n;
 }
 
-/*
- * Encode a buffer as base64 - simple and slow algorithm.
- */
-void
-rs_base64(unsigned char const *buf, int n, char *out)
+/** Encode a buffer as base64 - simple and slow algorithm. */
+void rs_base64(unsigned char const *buf, int n, char *out)
 {
     char const *b64 =
         "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
@@ -97,4 +91,3 @@ rs_base64(unsigned char const *buf, int n, char *out)
     }
     *out = 0;
 }
-
diff --git a/src/buf.c b/src/buf.c
index 5f026a1..0e9efa5 100644
--- a/src/buf.c
+++ b/src/buf.c
@@ -19,14 +19,14 @@
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
 
-                              /*
+                              /*=
                                | Pick a window, Jimmy, you're leaving.
                                */
 
 
-/*
- * buf.c -- Buffers that map between stdio file streams and librsync
- * streams.  As the stream consumes input and produces output, it is
+/** \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.
  *
diff --git a/src/checksum.c b/src/checksum.c
index 87a71ce..cdc68c7 100644
--- a/src/checksum.c
+++ b/src/checksum.c
@@ -33,7 +33,7 @@
 #include "blake2.h"
 
 
-/* A simple 32bit checksum that can be incrementally updated. */
+/** A simple 32bit checksum that can be incrementally updated. */
 rs_weak_sum_t rs_calc_weak_sum(void const *buf, size_t len)
 {
     Rollsum sum;
diff --git a/src/command.c b/src/command.c
index b5180c0..189ff40 100644
--- a/src/command.c
+++ b/src/command.c
@@ -19,7 +19,6 @@
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
 
-
 #include "config.h"
 
 #include <assert.h>
@@ -41,7 +40,7 @@ struct rs_op_kind_name const rs_op_kind_names[] = {
 };
 
 
-/*
+/**
  * Return a human-readable name for KIND.
  */
 char const * rs_op_kind_name(enum rs_op_kind kind)
diff --git a/src/command.h b/src/command.h
index a91cf78..6da530c 100644
--- a/src/command.h
+++ b/src/command.h
@@ -1,28 +1,27 @@
 /*= -*- c-basic-offset: 4; indent-tabs-mode: nil; -*-
  *
  * librsync -- library for network deltas
- * 
+ *
  * Copyright (C) 1999, 2000, 2001 by Martin Pool <mbp@sourcefrog.net>
  * Copyright (C) 1999 by Andrew Tridgell <tridge@samba.org>
- * 
+ *
  * 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.
  */
 
 
-/*
- * command.h -- Types of commands present in the encoding stream.
+/** \file command.h Types of commands present in the encoding stream.
  *
  * The vague idea is that eventually this file will be more abstract
  * than protocol.h, but it's not clear that will ever be required.
@@ -53,5 +52,3 @@ typedef struct rs_op_kind_name {
 } rs_op_kind_name_t;
 
 char const * rs_op_kind_name(enum rs_op_kind);
-
-
diff --git a/src/delta.c b/src/delta.c
index d2f0163..ab24e6d 100644
--- a/src/delta.c
+++ b/src/delta.c
@@ -27,8 +27,7 @@
                                  */
 
 
-/*
- * delta.c -- Generate in streaming mode an rsync delta given a set of
+/** \file delta.c -- Generate in streaming mode an rsync delta given a set of
  * signatures, and a new file.
  *
  * The size of blocks for signature generation is determined by the
@@ -111,7 +110,6 @@
  * from the scoop and scoop_pos adjusted. Everything gets complicated
  * because the tube can block. When the tube is blocked, no data can be
  * processed.
- *
  */
 
 /* used by rdiff, but now redundant */
diff --git a/src/emit.c b/src/emit.c
index 1267c51..228e5cb 100644
--- a/src/emit.c
+++ b/src/emit.c
@@ -46,7 +46,7 @@
 #include "job.h"
 
 
-/*
+/**
  * Write the magic for the start of a delta.
  */
 void
@@ -58,7 +58,7 @@ rs_emit_delta_header(rs_job_t *job)
 
 
 
-/* Write a LITERAL command. */
+/** Write a LITERAL command. */
 void
 rs_emit_literal_cmd(rs_job_t *job, int len)
 {
diff --git a/src/emit.h b/src/emit.h
index e3b774c..dd279c8 100644
--- a/src/emit.h
+++ b/src/emit.h
@@ -1,29 +1,25 @@
 /*= -*- c-basic-offset: 4; indent-tabs-mode: nil; -*-
  *
  * librsync -- dynamic caching and delta update in HTTP
- * 
+ *
  * Copyright (C) 2000, 2001 by Martin Pool <mbp@sourcefrog.net>
- * 
+ *
  * 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.
  */
 
-
-/*
- * emit.h -- How to emit commands to the client
- */
-
+/** \file emit.h How to emit commands to the client. */
 
 void rs_emit_delta_header(rs_job_t *);
 void rs_emit_literal_cmd(rs_job_t *, int len);
diff --git a/src/isprefix.h b/src/isprefix.h
index 28d5a6c..0c0a225 100644
--- a/src/isprefix.h
+++ b/src/isprefix.h
@@ -19,7 +19,5 @@
  */
 
 
-/*
- * Return true if TIP is a prefix of ICEBERG.
- */
+/** Return true if TIP is a prefix of ICEBERG. */
 int isprefix(char const *tip, char const *iceberg);
diff --git a/src/job.c b/src/job.c
index 14a9b43..1e44258 100644
--- a/src/job.c
+++ b/src/job.c
@@ -20,7 +20,7 @@
  */
 
 
-                              /*
+                              /*=
                                | The hard, lifeless I covered up the
                                | warm, pulsing It; protecting and
                                | sheltering.
diff --git a/src/job.h b/src/job.h
index 3aaff3e..d3c7b6b 100644
--- a/src/job.h
+++ b/src/job.h
@@ -22,8 +22,7 @@
 #include "mdfour.h"
 #include "rollsum.h"
 
-/**
- * \struct rs_job
+/** \struct rs_job
  * The contents of this structure are private.
  */
 struct rs_job {
diff --git a/src/librsync.h b/src/librsync.h
index 32404fc..257da49 100644
--- a/src/librsync.h
+++ b/src/librsync.h
@@ -20,7 +20,7 @@
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
 
-                              /*
+                              /*=
                                | You should never wear your best
                                | trousers when you go out to fight for
                                | freedom and liberty.
@@ -28,10 +28,7 @@
                                */
 
 
-/*!
- * \file librsync.h
- * \brief Public header for librsync.
- */
+/** \file librsync.h Public header for librsync. */
 
 #ifndef _RSYNC_H
 #define _RSYNC_H
@@ -58,7 +55,7 @@ typedef uint8_t rs_byte_t;
 typedef intmax_t rs_long_t;
 
 
-                          /*
+                          /*=
                            | "The IETF already has more than enough
                            | RFCs that codify the obvious, make
                            | stupidity illegal, support truth,
diff --git a/src/mksum.c b/src/mksum.c
index 8009ffd..fffaf22 100644
--- a/src/mksum.c
+++ b/src/mksum.c
@@ -23,9 +23,7 @@
 
 /**
  * \file mksum.c Generate file signatures.
- **/
-
-/*
+ *
  * Generating checksums is pretty easy, since we can always just
  * process whatever data is available.  When a whole block has
  * arrived, or we've reached the end of the file, we write the
diff --git a/src/msg.c b/src/msg.c
index 505dc13..1f9aa05 100644
--- a/src/msg.c
+++ b/src/msg.c
@@ -20,7 +20,7 @@
  */
 
 
-                              /*
+                              /*=
                                | Welcome to Arco AM/PM Mini-Market. We
                                | would like to advise our customers
                                | that any individual who offers to
diff --git a/src/netint.c b/src/netint.c
index 2fcf300..116eb93 100644
--- a/src/netint.c
+++ b/src/netint.c
@@ -1,34 +1,33 @@
 /*= -*- c-basic-offset: 4; indent-tabs-mode: nil; -*-
  *
  * librsync -- library for network deltas
- * 
+ *
  * Copyright (C) 1999, 2000, 2001 by Martin Pool <mbp@sourcefrog.net>
  * Copyright (C) 1999 by Andrew Tridgell <tridge@samba.org>
- * 
+ *
  * 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.
  */
 
-                            /*
+                            /*=
                              | Ummm, well, OK.  The network's the
                              | network, the computer's the
                              | computer.  Sorry for the confusion.
                              |        -- Sun Microsystems
                              */
 
-/*
- * Network-byte-order output to the tube.
+/** \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
@@ -37,9 +36,7 @@
  * All the netint operations are done in a fairly simpleminded way,
  * since we don't want to rely on stdint types that may not be
  * available on some platforms.
- */
-
-/*
+ *
  * TODO: If we don't have <stdint.h> (or perhaps even if we do),
  * determine endianness and integer size by hand and use that to do
  * our own conversion routines.  We possibly need this anyhow to do
@@ -147,7 +144,7 @@ rs_suck_byte(rs_job_t *job, unsigned char *v)
 {
     void *inb;
     rs_result result;
-    
+
     if ((result = rs_scoop_read(job, 1, &inb)) == RS_DONE)
         *v = *((unsigned char *) inb);
 
@@ -164,7 +161,7 @@ rs_suck_n4(rs_job_t *job, int *v)
     result = rs_suck_netint(job, &d, 4);
     *v = d;
     return result;
-}        
+}
 
 
 int rs_int_len(rs_long_t val)
diff --git a/src/patch.c b/src/patch.c
index cc95e06..2daef7e 100644
--- a/src/patch.c
+++ b/src/patch.c
@@ -20,11 +20,10 @@
  */
 
 
-                              /*
+                              /*=
                                | This is Tranquility Base.
                                */
 
-
 #include "config.h"
 
 #include <assert.h>
diff --git a/src/rdiff.c b/src/rdiff.c
index 5cdae3b..c9d4541 100644
--- a/src/rdiff.c
+++ b/src/rdiff.c
@@ -19,15 +19,14 @@
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
 
-                              /*
+                              /*=
                                | .. after a year and a day, mourning is
                                | dangerous to the survivor and troublesome
                                | to the dead.
                                |              -- Harold Bloom
                                */
 
-/*
- * rdiff.c -- Command-line network-delta tool.
+/** \file rdiff.c -- Command-line network-delta tool.
  *
  * TODO: Add a -z option to gzip/gunzip patches.  This would be
  * somewhat useful, but more importantly a good test of the streaming
@@ -397,6 +396,3 @@ int main(const int argc, const char *argv[])
     poptFreeContext(opcon);
     return result;
 }
-
-/* vim: et sw=4
- */
diff --git a/src/readsums.c b/src/readsums.c
index a7c72ff..8f4ddca 100644
--- a/src/readsums.c
+++ b/src/readsums.c
@@ -1,4 +1,4 @@
-/*=                     -*- c-basic-offset: 4; indent-tabs-mode: nil; -*-
+/*= -*- c-basic-offset: 4; indent-tabs-mode: nil; -*-
  *
  * librsync -- the library for network deltas
  *
@@ -21,8 +21,7 @@
  */
 
 
-/**
- * \file readsums.c
+/** \file readsums.c
  * \brief Load signatures from a file.
  */
 
diff --git a/src/scoop.c b/src/scoop.c
index 57a94cf..30d9e08 100644
--- a/src/scoop.c
+++ b/src/scoop.c
@@ -1,4 +1,4 @@
-/*=                    -*- c-basic-offset: 4; indent-tabs-mode: nil; -*-
+/*= -*- c-basic-offset: 4; indent-tabs-mode: nil; -*-
  *
  * librsync -- the library for network deltas
  *
@@ -19,8 +19,7 @@
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
 
-/*
- * scoop.c -- This file deals with readahead from caller-supplied
+/* \file scoop.c This file deals with readahead from caller-supplied
  * buffers.
  *
  * Many functions require a certain minimum amount of input to do their
@@ -52,7 +51,7 @@
  */
 
 
-                              /*
+                              /*=
                                | To walk on water you've gotta sink
                                | in the ice.
                                |   -- Shihad, `The General Electric'.
diff --git a/src/stream.c b/src/stream.c
index 227ea5d..591d639 100644
--- a/src/stream.c
+++ b/src/stream.c
@@ -19,12 +19,12 @@
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
 
-                     /*
-                      * Programming languages should be designed not
-                      * by piling feature on top of feature, but by
-                      * removing the weaknesses and restrictions that
-                      * make additional features appear necessary.
-                      *    -- Revised^5 Report on Scheme
+                     /*=
+                      | Programming languages should be designed not
+                      | by piling feature on top of feature, but by
+                      | removing the weaknesses and restrictions that
+                      | make additional features appear necessary.
+                      |    -- Revised^5 Report on Scheme
                       */
 
 
diff --git a/src/stream.h b/src/stream.h
index fb1f768..b52ac48 100644
--- a/src/stream.h
+++ b/src/stream.h
@@ -1,30 +1,31 @@
 /*= -*- c-basic-offset: 4; indent-tabs-mode: nil; -*-
  *
  * librsync -- library for network deltas
- * 
+ *
  * Copyright (C) 2000, 2001 by Martin Pool <mbp@sourcefrog.net>
- * 
+ *
  * 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.
  */
 
-                /* Two wars in a lifetime bear hard on the little places.
-                 * In winter when storms come rushing out of the dark,
-                 * And the bay boils like a cauldron of sharks,
-                 * The old remember the trenches at Paschendale
-                 * And sons who died on the Burma Railway. */
-
+                /*=
+                 | Two wars in a lifetime bear hard on the little places.
+                 | In winter when storms come rushing out of the dark,
+                 | And the bay boils like a cauldron of sharks,
+                 | The old remember the trenches at Paschendale
+                 | And sons who died on the Burma Railway.
+                 */
 
 int rs_buffers_is_empty(rs_buffers_t *stream);
 int rs_buffers_copy(rs_buffers_t *stream, int len);
diff --git a/src/trace.c b/src/trace.c
index 0e5580c..6156304 100644
--- a/src/trace.c
+++ b/src/trace.c
@@ -19,7 +19,7 @@
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
 
-                                     /*
+                                     /*=
                                       | Finality is death.
                                       | Perfection is finality.
                                       | Nothing is perfect.
diff --git a/src/trace.h b/src/trace.h
index f051fbc..1756856 100644
--- a/src/trace.h
+++ b/src/trace.h
@@ -19,15 +19,8 @@
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
 
-
-/*
- * TODO: A function like perror that includes strerror output.  Apache
- * does this by adding flags as well as the severity level which say
- * whether such information should be included.
- */
-
-
-/*
+/** \file trace.h logging functions.
+ *
  * trace may be turned off.
  *
  * error is always on, but you can return and continue in some way
@@ -35,6 +28,12 @@
  * fatal terminates the whole process
  */
 
+/*
+ * TODO: A function like perror that includes strerror output.  Apache
+ * does this by adding flags as well as the severity level which say
+ * whether such information should be included.
+ */
+
 #include <inttypes.h>
 /* Printf format patters for standard librsync types. */
 #define FMT_LONG "%"PRIdMAX
diff --git a/src/tube.c b/src/tube.c
index c892fdc..85b43b3 100644
--- a/src/tube.c
+++ b/src/tube.c
@@ -19,7 +19,7 @@
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
 
-                              /*
+                              /*=
                                | Where a calculator on the ENIAC is
                                | equpped with 18,000 vaccuum tubes and
                                | weighs 30 tons, computers in the
@@ -30,7 +30,7 @@
                                */
 
 
-/* tube: a somewhat elastic but fairly small buffer for data passing
+/** \file tube.c A somewhat elastic but fairly small buffer for data passing
  * through a stream.
  *
  * In most cases the iter can adjust to send just as much data will
diff --git a/src/util.c b/src/util.c
index 90ca516..aea862a 100644
--- a/src/util.c
+++ b/src/util.c
@@ -19,12 +19,10 @@
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
 
-
-                                /* 
+                                /*=
                                  | On heroin, I have all the answers.
                                  */
 
-
 #include "config.h"
 #include <stdlib.h>
 #include <string.h>
diff --git a/src/util.h b/src/util.h
index f6a20e9..8e3fe6a 100644
--- a/src/util.h
+++ b/src/util.h
@@ -26,7 +26,7 @@ void *rs_alloc_struct0(size_t size, char const *name);
 
 void rs_bzero(void *buf, size_t size);
 
-/*
+/**
  * Allocate and zero-fill an instance of TYPE.
  */
 #define rs_alloc_struct(type)				\
diff --git a/src/whole.c b/src/whole.c
index 50218b5..d4dfde0 100644
--- a/src/whole.c
+++ b/src/whole.c
@@ -19,7 +19,7 @@
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
 
-                              /*
+                              /*=
                                | Is it possible that software is not
                                | like anything else, that it is meant
                                | to be discarded: that the whole point
@@ -27,8 +27,6 @@
                                |        -- Alan Perlis
                                */
 
-
-
 #include "config.h"
 
 #include <assert.h>