From e0fde757fda15c0596914e6dc29dcd92a5b6448f Mon Sep 17 00:00:00 2001
From: Martin Pool <mbp@samba.org>
Date: Mon, 8 Apr 2002 03:38:36 +0000
Subject: [PATCH] Doc.

---
 cleanup.c    | 30 ++++++++++++++++++++++++------
 lib/compat.c | 41 ++++++++++++++++++++++++++++-------------
 2 files changed, 52 insertions(+), 19 deletions(-)

diff --git a/cleanup.c b/cleanup.c
index be2dd7d8..904fbaab 100644
--- a/cleanup.c
+++ b/cleanup.c
@@ -2,6 +2,7 @@
    
    Copyright (C) 1996-2000 by Andrew Tridgell
    Copyright (C) Paul Mackerras 1996
+   Copyright (C) 2002 by Martin Pool
    
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
@@ -20,9 +21,24 @@
 
 #include "rsync.h"
 
-/* handling the cleanup when a transfer is interrupted is tricky when
-   --partial is selected. We need to ensure that the partial file is
-   kept if any real data has been transferred */
+/**
+ * @file cleanup.c
+ *
+ * Code for handling interrupted transfers.  Depending on the @c
+ * --partial option, we may either delete the temporary file, or go
+ * ahead and overwrite the destination.  This second behaviour only
+ * occurs if we've sent literal data and therefore hopefully made
+ * progress on the transfer.
+ **/
+
+/**
+ * Set to True once literal data has been sent across the link for the
+ * current file. (????)
+ *
+ * Handling the cleanup when a transfer is interrupted is tricky when
+ * --partial is selected.  We need to ensure that the partial file is
+ * kept if any real data has been transferred.
+ **/
 int cleanup_got_literal=0;
 
 static char *cleanup_fname;
@@ -35,9 +51,11 @@ extern int io_error;
 
 pid_t cleanup_child_pid = -1;
 
-/*
- * Code is one of the RERR_* codes from errcode.h.
- */
+/**
+ * Eventually calls exit(), therefore does not return.
+ *
+ * @param code one of the RERR_* codes from errcode.h.
+ **/
 void _exit_cleanup(int code, const char *file, int line)
 {
 	int ocode = code;
diff --git a/lib/compat.c b/lib/compat.c
index bf013763..a783a01c 100644
--- a/lib/compat.c
+++ b/lib/compat.c
@@ -1,5 +1,6 @@
 /* 
    Copyright (C) Andrew Tridgell 1998
+   Copyright (C) 2002 by Martin Pool
    
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
@@ -16,11 +17,15 @@
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */
 
-/*
-  compatibility functions - replacing functions for platforms that don't
-  have them.
+/**
+ * @file compat.c
+ *
+ * Reimplementations of standard functions for platforms that don't
+ * have them.
+ **/
+
+
 
-  */
 #include "rsync.h"
 
 
@@ -78,9 +83,11 @@
 #endif
 
 #ifndef HAVE_STRPBRK
-/* Find the first ocurrence in S of any character in ACCEPT.  
-   derived from glibc 
-*/
+/**
+ * Find the first ocurrence in @p s of any character in @p accept.
+ *
+ * Derived from glibc 
+ **/
  char *strpbrk(const char *s, const char *accept)
 {
 	while (*s != '\0')  {
@@ -97,10 +104,14 @@
 
 
 #ifndef HAVE_STRLCPY
-/* Like strncpy but does not 0 fill the buffer and always null 
- * terminates. bufsize is the size of the destination buffer.
+/**
+ * Like strncpy but does not 0 fill the buffer and always null 
+ * terminates.
+ *
+ * @param bufsize is the size of the destination buffer.
  *
- * Returns the index of the terminating byte. */
+ * @return index of the terminating byte.
+ **/
  size_t strlcpy(char *d, const char *s, size_t bufsize)
 {
 	size_t len = strlen(s);
@@ -114,9 +125,13 @@
 #endif
 
 #ifndef HAVE_STRLCAT
-/* like strncat but does not 0 fill the buffer and always null 
-   terminates. bufsize is the length of the buffer, which should
-   be one more than the maximum resulting string length */
+/**
+ * Like strncat() but does not 0 fill the buffer and always null 
+ * terminates.
+ *
+ * @param bufsize length of the buffer, which should be one more than
+ * the maximum resulting string length.
+ **/
  size_t strlcat(char *d, const char *s, size_t bufsize)
 {
 	size_t len1 = strlen(d);
-- 
2.34.1