New API svn_stream_lazyopen_create - documentation

This new API was introduced recently and is intended to be back-ported to 1.8.0.  It needs better documentation.  I suggest:

[[[

Index: subversion/include/svn_io.h
===================================================================
--- subversion/include/svn_io.h    (revision 1471068)
+++ subversion/include/svn_io.h    (working copy)
@@ -1367,28 +1367,37 @@ svn_string_from_stream(svn_string_t **re
                        apr_pool_t *scratch_pool);
 
 
 /** A function type provided for use as a callback from
  * @c svn_stream_lazyopen_create().
  *
+ * The callback function shall open a new stream and set @a *stream to
+ * the stream object, allocated in @a result_pool.  @a baton is the
+ * callback baton that was passed to svn_stream_lazyopen_create().
+ *
+ * @a result_pool is the result pool that was passed to
+ * svn_stream_lazyopen_create().  The callback function may use
+ * @a scratch_pool for temporary allocations; the caller may clear or
+ * destroy @a scratch_pool any time after the function returns.
+ *
  * @since New in 1.8.
  */
 typedef svn_error_t *
 (*svn_stream_lazyopen_func_t)(svn_stream_t **stream,
                               void *baton,
                               apr_pool_t *result_pool,
                               apr_pool_t *scratch_pool);
 
 
 /** Return a generic stream which wraps another primary stream,
  * delaying the "opening" of that stream until the first time the
- * stream is accessed.
+ * returned stream is accessed.
  *
  * @a open_func and @a open_baton are a callback function/baton pair
- * invoked upon the first read of @a *stream which are used to open the
- * "real" source stream.
+ * which will be invoked upon the first read or write of the returned
+ * stream.  The callback shall open the primary stream.
  *
  * @note If the only "access" the returned stream gets is to close it
  * then @a open_func will only be called if @a open_on_close is TRUE.
  *
  * @since New in 1.8.
  */
]]]

Does that suggestion properly document it?

- Julian

--
Join WANdisco's free daily demo sessions on Scaling Subversion for the Enterprise
<http://www.wandisco.com/training/webinars>