Re: A clean-up task: delete "Use scratch_pool for temporary allocations" from doc strings

On Wed, Jan 30, 2013 at 6:09 PM, Julian Foad <julianfoad_at_btopenworld.com>wrote:

> No particular time frame, but a little clean-up task for
> anybody who has a touch of OCD or likes
> playing with regular expression search and replace, would be to remove
> the clause"Use scratch_pool for temporary allocations" from all our doc
> strings.
> Documentation should be helpful and concise; repeating universal truths is
> neither.

I beg to differ. I expect *all* parameters of *all* public functions
to be documented in one spot. If a documentation covers them
all, a reader knows that the docs are complete.

> Our 'scratch_pool' convention is universal. Not all code uses the
> convention, but it always means the same thing when it is used.
>

The same is true for many other parameters like svn_fs_t *fs,
svn_fs_root_t *root, svn_cancel_func_t cancel_func,
void *cancel_baton etc. What about those?

(The 'result_pool' convention, on the other hand, is a bit more involved.
> Results are not always allocated in result_pool, and there are often
> conditions attached such as "except some of the values in the result
> structure are shallow-copied from the inputs". So the public APIs at least
> should probably always be explicit about use of the result pool.)
>

Hm. Maybe, we should first review our API definitions and
rename all POOL parameters to either RESULT_POOL or
SCRATCH_POOL, maybe with a few exceptions.

-- Stefan^2.

-- 
Certified & Supported Apache Subversion Downloads:
*
http://www.wandisco.com/subversion/download
*