Various Doxygen syntax fixes or comment correction

4 files changed, 23 insertions, 25 deletions

diff --git a/NEWS.md b/NEWS.md
index 1295a45..40c138a 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -71,7 +71,7 @@ be binary and API compatible with the previous version.
 
  * Yet more large file support fixes.
  
- * C++ support for easy #include <librsync.h> in C++.
+ * `extern "C"` guards in librsync.h to let it be used from C++.
  
  * Removed Debian files from dist tarball.
  
diff --git a/src/job.c b/src/job.c
index 4486811..618a2fc 100644
--- a/src/job.c
+++ b/src/job.c
@@ -1,20 +1,19 @@
 /*= -*- c-basic-offset: 4; indent-tabs-mode: nil; -*-
  *
  * librsync -- the library for network deltas
- * $Id$
- * 
+ *
  * 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.
@@ -124,13 +123,14 @@ static rs_result rs_job_complete(rs_job_t *job, rs_result result)
 }
 
 
-/** 
+/**
  * \brief Run a ::rs_job_t state machine until it blocks
- * (::RS_BLOCKED), returns an error, or completes (::RS_COMPLETE).
+ * (::RS_BLOCKED), returns an error, or completes (::RS_DONE).
  *
  * \return The ::rs_result that caused iteration to stop.
  *
- * \param ending True if there is no more data after what's in the
+ * \c job->stream->eof_in should be true if there is no more data after what's
+ * in the
  * input buffer.  The final block checksum will run across whatever's
  * in there, without trying to accumulate anything else.
  */
@@ -144,7 +144,7 @@ rs_result rs_job_iter(rs_job_t *job, rs_buffers_t *buffers)
 
     result = rs_job_work(job, buffers);
 
-    if (result == RS_BLOCKED  ||  result == RS_DONE) 
+    if (result == RS_BLOCKED  ||  result == RS_DONE)
         if ((orig_in == buffers->avail_in)  &&  (orig_out == buffers->avail_out)
             && orig_in && orig_out) {
             rs_log(RS_LOG_ERR, "internal error: job made no progress "
@@ -251,4 +251,3 @@ rs_job_drive(rs_job_t *job, rs_buffers_t *buf,
 
     return result;
 }
-
diff --git a/src/librsync.h b/src/librsync.h
index ca46109..1527b31 100644
--- a/src/librsync.h
+++ b/src/librsync.h
@@ -38,9 +38,9 @@
 
  The library supports three basic operations:
 
-    -# Generating the signature S of a file A .
-    -# Calculating a delta D from S and a new file B.
-    -# Applying D to A to reconstruct B.
+    -# mksum: Generating the signature S of a file A .
+    -# delta: Calculating a delta D from S and a new file B.
+    -# path: Applying D to A to reconstruct B.
 
  The library also provides the \ref rdiff command-line tool, which
  makes this functionality available to users and scripting languages.
@@ -79,7 +79,7 @@
  data is available is kept in a small opaque ::rs_job_t structure.
  After creation of a job, repeated calls to rs_job_iter() in between
  filling and emptying the buffers keeps data flowing through the
- stream.  The ::rs_result_t values returned may indicate
+ stream.  The ::rs_result values returned may indicate
 
   - ::RS_DONE:  processing is complete
   - ::RS_BLOCKED: processing has blocked pending more data
@@ -501,7 +501,7 @@ rs_job_t *rs_delta_begin(rs_signature_t *);
 
 
 /**
- * \brief Read a signature from a file into an ::rs_signature_t structure
+ * \brief 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
diff --git a/src/patch.c b/src/patch.c
index 319bf44..369201f 100644
--- a/src/patch.c
+++ b/src/patch.c
@@ -1,20 +1,19 @@
 /*= -*- c-basic-offset: 4; indent-tabs-mode: nil; -*-
  *
  * librsync -- the library for network deltas
- * $Id$
- * 
+ *
  * 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.
@@ -246,7 +245,7 @@ static rs_result rs_patch_s_copying(rs_job_t *job)
     if (!job->basis_len) {
         /* Done! */
         job->statefn = rs_patch_s_cmdbyte;
-    } 
+    }
 
     return RS_RUNNING;
 }
@@ -281,14 +280,14 @@ static rs_result rs_patch_s_header(rs_job_t *job)
 
 
 /**
- * \brief Apply a \ref gloss_delta to a \ref gloss_basis to recreate
- * the new file.
+ * \brief 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
  * calling rs_job_iter() and updating the stream pointers.  When
  * finished, call rs_job_finish() to dispose of it.
  *
- * \param stream Contains pointers to input and output buffers, to be
+ * \c job->stream Contains pointers to input and output buffers, to be
  * adjusted by caller on each iteration.
  *
  * \param copy_cb Callback used to retrieve content from the basis