From d22dba5a3ad6cd0e0be4c07527218c6b48fd5bd3 Mon Sep 17 00:00:00 2001
From: Martin Mares <mj@ucw.cz>
Date: Sun, 15 Feb 2009 00:33:58 +0100
Subject: [PATCH] Logging: Removed duplicate comments.

A function should be documented at a single place, preferably in a header file.

Also removed a couple of comments at functions whose usage is perfectly
clear from their name.
---
 ucw/log-file.c   |  7 -------
 ucw/log-stream.c | 11 -----------
 ucw/log-syslog.c |  6 +-----
 ucw/log.h        |  3 ++-
 4 files changed, 3 insertions(+), 24 deletions(-)

diff --git a/ucw/log-file.c b/ucw/log-file.c
index 0b8ed66c..cd0d037c 100644
--- a/ucw/log-file.c
+++ b/ucw/log-file.c
@@ -93,7 +93,6 @@ do_log_switch(struct file_stream *fs, struct tm *tm)
   return switched;
 }
 
-/* destructor for standard files */
 static void
 file_close(struct log_stream *ls)
 {
@@ -104,7 +103,6 @@ file_close(struct log_stream *ls)
   xfree(fs->orig_name);
 }
 
-/* handler for standard files */
 static int
 file_handler(struct log_stream *ls, struct log_msg *m)
 {
@@ -117,8 +115,6 @@ file_handler(struct log_stream *ls, struct log_msg *m)
   return 0;
 }
 
-/* assign log to a file descriptor */
-/* initialize with the default formatting, does NOT close the descriptor */
 struct log_stream *
 log_new_fd(int fd)
 {
@@ -154,8 +150,6 @@ do_log_new_file(const char *path, uns more_flags)
   return ls;
 }
 
-/* open() a file (append mode) */
-/* initialize with the default formatting */
 struct log_stream *
 log_new_file(const char *path)
 {
@@ -189,7 +183,6 @@ log_switch_enable(void)
   log_switch_nest--;
 }
 
-/* Emulate the old single-file interface: close the existing log file and open a new one. */
 void
 log_file(const char *name)
 {
diff --git a/ucw/log-stream.c b/ucw/log-stream.c
index 097faef9..f65373ce 100644
--- a/ucw/log-stream.c
+++ b/ucw/log-stream.c
@@ -52,8 +52,6 @@ log_init_module(void)
   log_add_substream(ls, &log_stream_default);
 }
 
-/* Close all open streams, un-initialize the module, free all memory,
- * and fall back to using only log_stream_default. */
 void
 log_close_all(void)
 {
@@ -76,8 +74,6 @@ log_close_all(void)
   log_initialized = 0;
 }
 
-/* Add a new substream. The parent stream takes a reference on the substream,
- * preventing it from being closed as long as it is linked. */
 void
 log_add_substream(struct log_stream *where, struct log_stream *what)
 {
@@ -89,9 +85,6 @@ log_add_substream(struct log_stream *where, struct log_stream *what)
   clist_add_tail(&where->substreams, &n->n);
 }
 
-/* Remove all occurrences of a substream together with the references they
- * keep. If a substream becomes unreferenced, it is closed. If what is NULL,
- * all substreams are removed. Returns the number of deleted entries. */
 int
 log_rm_substream(struct log_stream *where, struct log_stream *what)
 {
@@ -110,7 +103,6 @@ log_rm_substream(struct log_stream *where, struct log_stream *what)
   return cnt;
 }
 
-/* Return a pointer to a new stream with no handler and an empty substream list. */
 struct log_stream *
 log_new_stream(size_t size)
 {
@@ -143,9 +135,6 @@ log_new_stream(size_t size)
   return log_ref_stream(l);
 }
 
-/* Remove a reference on a stream and close it if it was the last reference.
- * Closing automatically unlinks all substreams and closes them if they are
- * no longer referenced. Returns 1 if the stream has been really closed. */
 int
 log_close_stream(struct log_stream *ls)
 {
diff --git a/ucw/log-syslog.c b/ucw/log-syslog.c
index 0aa6e2d6..dae84005 100644
--- a/ucw/log-syslog.c
+++ b/ucw/log-syslog.c
@@ -18,7 +18,6 @@ struct syslog_stream {
   int facility;
 };
 
-/* Destructor */
 static void
 syslog_close(struct log_stream *ls)
 {
@@ -26,7 +25,7 @@ syslog_close(struct log_stream *ls)
     xfree(ls->name);
 }
 
-/* convert severity level to syslog constants */
+/* Convert severity level to syslog constants */
 static int
 syslog_level(int level)
 {
@@ -61,9 +60,6 @@ syslog_handler(struct log_stream *ls, struct log_msg *m)
   return 0;
 }
 
-/* assign log to a syslog facility */
-/* initialize with no formatting (syslog adds these inforamtion) */
-/* name is optional prefix (NULL for none) */
 struct log_stream *
 log_new_syslog(int facility, const char *name)
 {
diff --git a/ucw/log.h b/ucw/log.h
index b5383cdf..f7baf629 100644
--- a/ucw/log.h
+++ b/ucw/log.h
@@ -128,7 +128,8 @@ static inline struct log_stream *log_ref_stream(struct log_stream *ls)
 }
 
 /**
- * Link a substream to a stream. The substream gains a reference.
+ * Link a substream to a stream. The substream gains a reference, preventing
+ * it from being freed until it is unlinked.
  **/
 void log_add_substream(struct log_stream *where, struct log_stream *what);
 
-- 
2.39.2