Re: [PATCH] Doc string for svn_wc__db_pristine_read()

Julian Foad wrote:
> Proposed doc string for review. Don't fully understand relationship
> between the "db" and "wri" params. Gstein/neels/me just started talking
> about this on IRC but I've got to go now. Please adjust as necessary and
> commit.
>
> [[[
> * subversion/libsvn_wc/wc_db.h
> (svn_wc__db_pristine_read): Add a doc string.
>
> Index: subversion/libsvn_wc/wc_db.h
> ===================================================================
> --- subversion/libsvn_wc/wc_db.h (revision 909475)
> +++ subversion/libsvn_wc/wc_db.h (working copy)
> @@ -784,7 +784,13 @@
> } svn_wc__db_checkmode_t;
>
>
> -/* ### @a contents may NOT be NULL. */
> +/* Set *CONTENTS to a new stream, from which the caller can read the pristine
> + * text that matches CHECKSUM. Find the text in the database DB.
> + * ### ? Limit the search to texts associated with the WC rooted at WRI_ABSPATH.

My version of a doc string for svn_wc__db_pristine_read() would be:

"
Set *CONTENTS to a new stream, from which the caller can read the pristine
text given by CHECKSUM, as related to the working copy indicated by
WRI_ABSPATH which is managed by DB.

Simply open a stream on the contents, do not verify correctness of the
pristine in any way other than being able to supply its contents (see
svn_wc__db_pristine_check()). Use DB's pristine store.

Implementation note: This does not query the PRISTINE database table, it
  simply opens the pristine file for reading. If this pristine file does
  not exist, return an error. ### Which error?
"

~Neels

> + *
> + * Allocate the new stream in RESULT_POOL, and arrange for the stream to be
> + * closed on pool destruction if the caller has not already closed it by then.
> + * */
> svn_error_t *
> svn_wc__db_pristine_read(svn_stream_t **contents,
> svn_wc__db_t *db,
>
> ]]]
>
> - Julian
>
>