[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: svn commit: r17834 - in trunk/subversion: include libsvn_client

From: Julian Foad <julianfoad_at_btopenworld.com>
Date: 2005-12-18 22:52:59 CET

Peter N. Lundblad wrote:
>>
>>-/** Convenience function for creating streams which operate on APR
>>- * files. For convenience, if @a file is NULL then svn_stream_empty(pool)
>>- * is returned. Note that the stream returned by these operations is not
>>- * considered to "own" the underlying file, meaning that svn_stream_close()
>>- * on the stream will not close the file.
>>+/** Function to create streams which operate on APR * files.
>
> These "Function to" sound odd to me; that shouldn't be part of the
> docstring. (Same below.)

The attached pending patch of mine contains a better doc string for
svn_stream_from_aprfile(), which you might like to use now.

- Julian

Clarify some API doc strings.

* subversion/include/svn_io.h
  (svn_read_fn_t, svn_write_fn_t, svn_close_fn_t,
   svn_stream_read, svn_stream_write, svn_stream_close):
    Refer the reader to documentation of svn_stream_t for details.
  (svn_stream_create, svn_stream_empty, svn_stream_from_aprfile):
    Clarify.
  (svn_stream_for_stdout): ### Something odd here.

Index: subversion/include/svn_io.h
===================================================================
--- subversion/include/svn_io.h (revision 17758)
+++ subversion/include/svn_io.h (working copy)
@@ -517,21 +517,21 @@
 
 
 
-/** Read handler function for a generic stream. */
+/** Read handler function for a generic stream. @see svn_stream_t. */
 typedef svn_error_t *(*svn_read_fn_t) (void *baton,
                                        char *buffer,
                                        apr_size_t *len);
 
-/** Write handler function for a generic stream. */
+/** Write handler function for a generic stream. @see svn_stream_t. */
 typedef svn_error_t *(*svn_write_fn_t) (void *baton,
                                         const char *data,
                                         apr_size_t *len);
 
-/** Close handler function for a generic stream. */
+/** Close handler function for a generic stream. @see svn_stream_t. */
 typedef svn_error_t *(*svn_close_fn_t) (void *baton);
 
 
-/** Creating a generic stream. */
+/** Create a generic stream that will use the given @a baton. @see svn_stream_t. */
 svn_stream_t *svn_stream_create (void *baton, apr_pool_t *pool);
 
 /** Set @a stream's baton to @a baton */
@@ -547,21 +547,20 @@
 void svn_stream_set_close (svn_stream_t *stream, svn_close_fn_t close_fn);
 
 
-/** Convenience function to create a generic stream which is empty. */
+/** Create a stream that is empty for reading and infinite for writing. */
 svn_stream_t *svn_stream_empty (apr_pool_t *pool);
 
 
-/** Convenience function for creating streams which operate on APR
- * files. For convenience, if @a file is NULL then svn_stream_empty(pool)
- * is returned. Note that the stream returned by these operations is not
- * considered to "own" the underlying file, meaning that svn_stream_close()
- * on the stream will not close the file.
+/** Create a stream that operates on an APR file.
+ * For convenience, if @a file is NULL then return svn_stream_empty(pool).
+ * Note that the stream returned is not considered to "own" the underlying
+ * file, meaning that svn_stream_close() on the stream will not close the file.
  */
 svn_stream_t *svn_stream_from_aprfile (apr_file_t *file, apr_pool_t *pool);
 
 /** Set @a *out to a generic stream connected to stdout, allocated in
  * @a pool. The stream and its underlying APR handle will be closed
- * when @a pool is cleared or destroyed.
+ * when @a pool is cleared or destroyed. ### Why is that sentence here and not in any other stream constructor?
  */
 svn_error_t *svn_stream_for_stdout (svn_stream_t **out, apr_pool_t *pool);
 
@@ -604,15 +603,15 @@
                                        unsigned char **write_digest,
                                        apr_pool_t *pool);
 
-/** Read from a generic stream. */
+/** Read from a generic stream. @see svn_stream_t. */
 svn_error_t *svn_stream_read (svn_stream_t *stream, char *buffer,
                               apr_size_t *len);
 
-/** Write to a generic stream. */
+/** Write to a generic stream. @see svn_stream_t. */
 svn_error_t *svn_stream_write (svn_stream_t *stream, const char *data,
                                apr_size_t *len);
 
-/** Close a generic stream. */
+/** Close a generic stream. @see svn_stream_t. */
 svn_error_t *svn_stream_close (svn_stream_t *stream);
 
 

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Sun Dec 18 22:53:43 2005

This is an archived mail posted to the Subversion Dev mailing list.