[PATCH 4/9 v2] Comment and whitespace changes

[Gary Benson <gbenson@redhat.com>]

Comments on the various implementations of target fileio functions
duplicate information documented in target.h.  This commit replaces
the duplicated documentation with breadcrumbs, and inserts blank
lines to separate comments from the functions they describe where
necessary.

gdb/ChangeLog:

	* inf-child.c (inf_child_fileio_open): Replace comment.
	(inf_child_fileio_pwrite): Likewise.
	(inf_child_fileio_pread): Likewise.
	(inf_child_fileio_fstat): Insert blank line before comment.
	(inf_child_fileio_close): Replace comment.
	(inf_child_fileio_unlink): Likewise.
	(inf_child_fileio_readlink): Likewise.
	* remote.c (remote_hostio_open): Likewise.
	(remote_hostio_pread): Likewise.
	(remote_hostio_pwrite): Likewise.
	(remote_hostio_close): Likewise.
	(remote_hostio_unlink): Likewise.
	(remote_hostio_readlink): Likewise.
	(remote_hostio_fstat): Likewise.
	(remote_filesystem_is_local): Likewise.
	* target.c (target_fileio_open): Likewise.
	(target_fileio_pwrite): Likewise.
	(target_fileio_pread): Likewise.
	(target_fileio_fstat): Insert blank line before comment.
	(target_fileio_close): Replace comment.
	(target_fileio_unlink): Likewise.
	(target_fileio_readlink): Likewise.
	(target_fileio_read_alloc): Likewise.
	(target_fileio_read_stralloc): Likewise.
---
 gdb/ChangeLog   |   27 +++++++++++++++++++++++++++
 gdb/inf-child.c |   29 +++++++++++++----------------
 gdb/remote.c    |   29 ++++++++---------------------
 gdb/target.c    |   39 +++++++++++++++------------------------
 4 files changed, 63 insertions(+), 61 deletions(-)

diff --git a/gdb/inf-child.c b/gdb/inf-child.c
index 084dfa1..181a745 100644
--- a/gdb/inf-child.c
+++ b/gdb/inf-child.c
@@ -204,9 +204,8 @@ inf_child_pid_to_exec_file (struct target_ops *self, int pid)
   return NULL;
 }
 
-/* Open FILENAME on the target, using FLAGS and MODE.  Return a
-   target file descriptor, or -1 if an error occurs (and set
-   *TARGET_ERRNO).  */
+/* Implementation of to_fileio_open.  */
+
 static int
 inf_child_fileio_open (struct target_ops *self,
 		       const char *filename, int flags, int mode,
@@ -230,9 +229,8 @@ inf_child_fileio_open (struct target_ops *self,
   return fd;
 }
 
-/* Write up to LEN bytes from WRITE_BUF to FD on the target.
-   Return the number of bytes written, or -1 if an error occurs
-   (and set *TARGET_ERRNO).  */
+/* Implementation of to_fileio_pwrite.  */
+
 static int
 inf_child_fileio_pwrite (struct target_ops *self,
 			 int fd, const gdb_byte *write_buf, int len,
@@ -259,9 +257,8 @@ inf_child_fileio_pwrite (struct target_ops *self,
   return ret;
 }
 
-/* Read up to LEN bytes FD on the target into READ_BUF.
-   Return the number of bytes read, or -1 if an error occurs
-   (and set *TARGET_ERRNO).  */
+/* Implementation of to_fileio_pread.  */
+
 static int
 inf_child_fileio_pread (struct target_ops *self,
 			int fd, gdb_byte *read_buf, int len,
@@ -289,6 +286,7 @@ inf_child_fileio_pread (struct target_ops *self,
 }
 
 /* Implementation of to_fileio_fstat.  */
+
 static int
 inf_child_fileio_fstat (struct target_ops *self, int fd,
 			struct stat *sb, int *target_errno)
@@ -302,8 +300,8 @@ inf_child_fileio_fstat (struct target_ops *self, int fd,
   return ret;
 }
 
-/* Close FD on the target.  Return 0, or -1 if an error occurs
-   (and set *TARGET_ERRNO).  */
+/* Implementation of to_fileio_close.  */
+
 static int
 inf_child_fileio_close (struct target_ops *self, int fd, int *target_errno)
 {
@@ -316,8 +314,8 @@ inf_child_fileio_close (struct target_ops *self, int fd, int *target_errno)
   return ret;
 }
 
-/* Unlink FILENAME on the target.  Return 0, or -1 if an error
-   occurs (and set *TARGET_ERRNO).  */
+/* Implementation of to_fileio_unlink.  */
+
 static int
 inf_child_fileio_unlink (struct target_ops *self,
 			 const char *filename, int *target_errno)
@@ -331,9 +329,8 @@ inf_child_fileio_unlink (struct target_ops *self,
   return ret;
 }
 
-/* Read value of symbolic link FILENAME on the target.  Return a
-   null-terminated string allocated via xmalloc, or NULL if an error
-   occurs (and set *TARGET_ERRNO).  */
+/* Implementation of to_fileio_readlink.  */
+
 static char *
 inf_child_fileio_readlink (struct target_ops *self,
 			   const char *filename, int *target_errno)
diff --git a/gdb/remote.c b/gdb/remote.c
index 099ddbb..6820dc8 100644
--- a/gdb/remote.c
+++ b/gdb/remote.c
@@ -9879,9 +9879,7 @@ remote_hostio_send_command (int command_bytes, int which_packet,
   return ret;
 }
 
-/* Open FILENAME on the remote target, using FLAGS and MODE.  Return a
-   remote file descriptor, or -1 if an error occurs (and set
-   *REMOTE_ERRNO).  */
+/* Implementation of to_fileio_open.  */
 
 static int
 remote_hostio_open (struct target_ops *self,
@@ -9907,9 +9905,7 @@ remote_hostio_open (struct target_ops *self,
 				     remote_errno, NULL, NULL);
 }
 
-/* Write up to LEN bytes from WRITE_BUF to FD on the remote target.
-   Return the number of bytes written, or -1 if an error occurs (and
-   set *REMOTE_ERRNO).  */
+/* Implementation of to_fileio_pwrite.  */
 
 static int
 remote_hostio_pwrite (struct target_ops *self,
@@ -9936,9 +9932,7 @@ remote_hostio_pwrite (struct target_ops *self,
 				     remote_errno, NULL, NULL);
 }
 
-/* Read up to LEN bytes FD on the remote target into READ_BUF
-   Return the number of bytes read, or -1 if an error occurs (and
-   set *REMOTE_ERRNO).  */
+/* Implementation of to_fileio_pread.  */
 
 static int
 remote_hostio_pread (struct target_ops *self,
@@ -9977,8 +9971,7 @@ remote_hostio_pread (struct target_ops *self,
   return ret;
 }
 
-/* Close FD on the remote target.  Return 0, or -1 if an error occurs
-   (and set *REMOTE_ERRNO).  */
+/* Implementation of to_fileio_close.  */
 
 static int
 remote_hostio_close (struct target_ops *self, int fd, int *remote_errno)
@@ -9995,8 +9988,7 @@ remote_hostio_close (struct target_ops *self, int fd, int *remote_errno)
 				     remote_errno, NULL, NULL);
 }
 
-/* Unlink FILENAME on the remote target.  Return 0, or -1 if an error
-   occurs (and set *REMOTE_ERRNO).  */
+/* Implementation of to_fileio_unlink.  */
 
 static int
 remote_hostio_unlink (struct target_ops *self,
@@ -10015,9 +10007,7 @@ remote_hostio_unlink (struct target_ops *self,
 				     remote_errno, NULL, NULL);
 }
 
-/* Read value of symbolic link FILENAME on the remote target.  Return
-   a null-terminated string allocated via xmalloc, or NULL if an error
-   occurs (and set *REMOTE_ERRNO).  */
+/* Implementation of to_fileio_readlink.  */
 
 static char *
 remote_hostio_readlink (struct target_ops *self,
@@ -10054,9 +10044,7 @@ remote_hostio_readlink (struct target_ops *self,
   return ret;
 }
 
-/* Read information about the open file FD on the remote target
-   into ST.  Return 0 on success, or -1 if an error occurs (and
-   set *REMOTE_ERRNO).  */
+/* Implementation of to_fileio_fstat.  */
 
 static int
 remote_hostio_fstat (struct target_ops *self,
@@ -10116,8 +10104,7 @@ remote_hostio_fstat (struct target_ops *self,
   return 0;
 }
 
-/* Return nonzero if the filesystem accessed by the target_fileio_*
-   methods is the local filesystem, zero otherwise.  */
+/* Implementation of to_filesystem_is_local.  */
 
 static int
 remote_filesystem_is_local (struct target_ops *self)
diff --git a/gdb/target.c b/gdb/target.c
index 306c21d..c0acaa9 100644
--- a/gdb/target.c
+++ b/gdb/target.c
@@ -2756,9 +2756,8 @@ release_fileio_fd (int fd, fileio_fh_t *fh)
 #define fileio_fd_to_fh(fd) \
   VEC_index (fileio_fh_t, fileio_fhandles, (fd))
 
-/* Open FILENAME on the target, using FLAGS and MODE.  Return a
-   target file descriptor, or -1 if an error occurs (and set
-   *TARGET_ERRNO).  */
+/* See target.h.  */
+
 int
 target_fileio_open (const char *filename, int flags, int mode,
 		    int *target_errno)
@@ -2789,9 +2788,8 @@ target_fileio_open (const char *filename, int flags, int mode,
   return -1;
 }
 
-/* Write up to LEN bytes from WRITE_BUF to FD on the target.
-   Return the number of bytes written, or -1 if an error occurs
-   (and set *TARGET_ERRNO).  */
+/* See target.h.  */
+
 int
 target_fileio_pwrite (int fd, const gdb_byte *write_buf, int len,
 		      ULONGEST offset, int *target_errno)
@@ -2814,9 +2812,8 @@ target_fileio_pwrite (int fd, const gdb_byte *write_buf, int len,
   return ret;
 }
 
-/* Read up to LEN bytes FD on the target into READ_BUF.
-   Return the number of bytes read, or -1 if an error occurs
-   (and set *TARGET_ERRNO).  */
+/* See target.h.  */
+
 int
 target_fileio_pread (int fd, gdb_byte *read_buf, int len,
 		     ULONGEST offset, int *target_errno)
@@ -2840,6 +2837,7 @@ target_fileio_pread (int fd, gdb_byte *read_buf, int len,
 }
 
 /* See target.h.  */
+
 int
 target_fileio_fstat (int fd, struct stat *sb, int *target_errno)
 {
@@ -2858,8 +2856,8 @@ target_fileio_fstat (int fd, struct stat *sb, int *target_errno)
   return ret;
 }
 
-/* Close FD on the target.  Return 0, or -1 if an error occurs
-   (and set *TARGET_ERRNO).  */
+/* See target.h.  */
+
 int
 target_fileio_close (int fd, int *target_errno)
 {
@@ -2881,8 +2879,8 @@ target_fileio_close (int fd, int *target_errno)
   return ret;
 }
 
-/* Unlink FILENAME on the target.  Return 0, or -1 if an error
-   occurs (and set *TARGET_ERRNO).  */
+/* See target.h.  */
+
 int
 target_fileio_unlink (const char *filename, int *target_errno)
 {
@@ -2906,9 +2904,8 @@ target_fileio_unlink (const char *filename, int *target_errno)
   return -1;
 }
 
-/* Read value of symbolic link FILENAME on the target.  Return a
-   null-terminated string allocated via xmalloc, or NULL if an error
-   occurs (and set *TARGET_ERRNO).  */
+/* See target.h.  */
+
 char *
 target_fileio_readlink (const char *filename, int *target_errno)
 {
@@ -3006,9 +3003,7 @@ target_fileio_read_alloc_1 (const char *filename,
     }
 }
 
-/* Read target file FILENAME.  Store the result in *BUF_P and return
-   the size of the transferred data.  See the declaration in "target.h"
-   function for more information about the return value.  */
+/* See target.h.  */
 
 LONGEST
 target_fileio_read_alloc (const char *filename, gdb_byte **buf_p)
@@ -3016,11 +3011,7 @@ target_fileio_read_alloc (const char *filename, gdb_byte **buf_p)
   return target_fileio_read_alloc_1 (filename, buf_p, 0);
 }
 
-/* Read target file FILENAME.  The result is NUL-terminated and
-   returned as a string, allocated using xmalloc.  If an error occurs
-   or the transfer is unsupported, NULL is returned.  Empty objects
-   are returned as allocated but empty strings.  A warning is issued
-   if the result contains any embedded NUL bytes.  */
+/* See target.h.  */
 
 char *
 target_fileio_read_stralloc (const char *filename)
-- 
1.7.1