Re: [PATCH] Improve wording of svn_delta_editor_t's absent_(file|directory) callback functions.

Trent Nelson wrote on Tue, Jan 10, 2012 at 20:56:27 -0800:
> Howdy folks,
>

Hi!

> The current wording of svn_delta_editor_t's absent_(file|directory)
> callback functions is a bit misleading:
>
> "In the (file|directory) ... but cannot be conveyed to the
> consumer (perhaps because of authorization restrictions)."
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> Because of that wording, I just spent a chunk of time looking through
> the code trying to find if these callbacks would be invoked for any
> reason *other* than an authorization restriction.
>
> I've concluded that no, they wouldn't :-)
>

Sounds like this is a good thing to clarify...

> +++ subversion/include/svn_delta.h (working copy)
> @@ -916,8 +916,8 @@
>
> /** In the directory represented by @a parent_baton, indicate that
> * @a path is present as a subdirectory in the edit source, but
> - * cannot be conveyed to the edit consumer (perhaps because of
> - * authorization restrictions).
> + * cannot be conveyed to the edit consumer because of authorization
> + * restrictions.
> *

But I disagree with this fix: I think the original language here was
inetntionally vague due to forwards compatibility considerations. How
about saying that _currently_ (1.7) the only possible cause is authz
restrictions?

> * Any temporary allocations may be performed in @a scratch_pool.
> */
> @@ -1040,8 +1040,8 @@

What about svn_editor_add_absent()? Is its docstring okay?
Received on 2012-01-11 06:06:46 CET