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