[patch] Improve comments in dcache.c, target.c.

[dje at google dot com (Doug Evans)]

Hi.
ref: http://sourceware.org/ml/gdb-patches/2009-10/msg00511.html

This patch tweaks/adds a few comments to dcache.c, target.c.
I'll check it in on Monday if there are no objections.

2009-10-23  Doug Evans  <dje@google.com>

	* dcache.c (dcache_hit, dcache_read_line): Tweak comments.
	(dcache_peek_byte, dcache_init, dcache_xfer_memory): Ditto.
	* target.c (memory_xfer_partial): Tweak comments.
	(target_xfer_partial, target_write_memory): Add comment.
	(target_read_partial): Remove note from 2003-10-21.
	(target_read, target_write): Add comments.

Index: dcache.c
===================================================================
RCS file: /cvs/src/src/gdb/dcache.c,v
retrieving revision 1.36
diff -u -p -r1.36 dcache.c
--- dcache.c	31 Aug 2009 20:18:45 -0000	1.36
+++ dcache.c	23 Oct 2009 18:38:31 -0000
@@ -175,7 +175,7 @@ dcache_invalidate_line (DCACHE *dcache, 
 }
 
 /* If addr is present in the dcache, return the address of the block
-   containing it.  */
+   containing it.  Otherwise return NULL.  */
 
 static struct dcache_block *
 dcache_hit (DCACHE *dcache, CORE_ADDR addr)
@@ -193,7 +193,9 @@ dcache_hit (DCACHE *dcache, CORE_ADDR ad
   return db;
 }
 
-/* Fill a cache line from target memory.  */
+/* Fill a cache line from target memory.
+   The result is 1 for success, 0 if the (entire) cache line
+   wasn't readable.  */
 
 static int
 dcache_read_line (DCACHE *dcache, struct dcache_block *db)
@@ -286,7 +288,7 @@ dcache_alloc (DCACHE *dcache, CORE_ADDR 
   return db;
 }
 
-/* Using the data cache DCACHE return the contents of the byte at
+/* Using the data cache DCACHE, store in *PTR the contents of the byte at
    address ADDR in the remote machine.  
 
    Returns 1 for success, 0 for error.  */
@@ -341,7 +343,7 @@ dcache_splay_tree_compare (splay_tree_ke
     return -1;
 }
 
-/* Initialize the data cache.  */
+/* Allocate and initialize a data cache.  */
 
 DCACHE *
 dcache_init (void)
@@ -388,7 +390,11 @@ dcache_free (DCACHE *dcache)
    to or from debugger address MYADDR.  Write to inferior if SHOULD_WRITE is
    nonzero. 
 
-   The meaning of the result is the same as for target_write.  */
+   Return the number of bytes actually transfered, or -1 if the
+   transfer is not supported or otherwise fails.  Return of a non-negative
+   value less than LEN indicates that no further transfer is possible.
+   NOTE: This is different than the to_xfer_partial interface, in which
+   positive values less than LEN mean further transfers may be possible.  */
 
 int
 dcache_xfer_memory (struct target_ops *ops, DCACHE *dcache,
Index: target.c
===================================================================
RCS file: /cvs/src/src/gdb/target.c,v
retrieving revision 1.229
diff -u -p -r1.229 target.c
--- target.c	20 Oct 2009 11:09:01 -0000	1.229
+++ target.c	23 Oct 2009 18:38:31 -0000
@@ -1181,8 +1181,8 @@ target_section_by_addr (struct target_op
   return NULL;
 }
 
-/* Perform a partial memory transfer.  The arguments and return
-   value are just as for target_xfer_partial.  */
+/* Perform a partial memory transfer.
+   For docs see target.h, to_xfer_partial.  */
 
 static LONGEST
 memory_xfer_partial (struct target_ops *ops, enum target_object object,
@@ -1360,6 +1360,8 @@ make_show_memory_breakpoints_cleanup (in
 		       (void *) (uintptr_t) current);
 }
 
+/* For docs see target.h, to_xfer_partial.  */
+
 static LONGEST
 target_xfer_partial (struct target_ops *ops,
 		     enum target_object object, const char *annex,
@@ -1474,6 +1476,11 @@ target_read_stack (CORE_ADDR memaddr, gd
     return EIO;
 }
 
+/* Write LEN bytes from MYADDR to target memory at address MEMADDR.
+   Returns either 0 for success or an errno value if any error occurs.
+   If an error occurs, no guarantee is made about how much data got written.
+   Callers that can deal with partial writes should call target_write.  */
+
 int
 target_write_memory (CORE_ADDR memaddr, const gdb_byte *myaddr, int len)
 {
@@ -1637,11 +1644,7 @@ current_xfer_partial (struct target_ops 
     return -1;
 }
 
-/* Target vector read/write partial wrapper functions.
-
-   NOTE: cagney/2003-10-21: I wonder if having "to_xfer_partial
-   (inbuf, outbuf)", instead of separate read/write methods, make life
-   easier.  */
+/* Target vector read/write partial wrapper functions.  */
 
 static LONGEST
 target_read_partial (struct target_ops *ops,
@@ -1662,6 +1665,9 @@ target_write_partial (struct target_ops 
 }
 
 /* Wrappers to perform the full transfer.  */
+
+/* For docs on target_write see target.h.  */
+
 LONGEST
 target_read (struct target_ops *ops,
 	     enum target_object object,
@@ -1750,7 +1756,6 @@ target_read_until_error (struct target_o
   return len;
 }
 
-
 /* An alternative to target_write with progress callbacks.  */
 
 LONGEST
@@ -1786,6 +1791,8 @@ target_write_with_progress (struct targe
   return len;
 }
 
+/* For docs on target_write see target.h.  */
+
 LONGEST
 target_write (struct target_ops *ops,
 	      enum target_object object,