On Wed, Jan 30, 2013 at 6:09 PM, Julian Foad <julianf...@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 *
