API/Interface design questions

Several of the functions which I have been working on to support the property
keyword expansion have had altered signatures. Specifically, these two:

        svn_subst_keywords_differ()
        svn_subst_copy_and_translate()

have had a pool term added. So for API compatibility, I need to create new
functions and turn the above into wrappers, so I was hoping for some guidance on
appropriate names for the new functions (appending "_pool" seems kind of lame).

At the same time, I see that HACKING mentions "public and semi-public"
functions, but doesn't provide any guidance as to when to use each. In my
opinion, based on the usage in the core files (a single call from props.c), as
well as the specialized nature of the input parameters, the first function above
should never have been part of the public API. The second is a more difficult
call (used in multiple files); I'd have to analyze all of the other usages.

Was there a discussion about how to decide when a function belongs in the public
API? The list archive was not especially helpful (ETOOMANYEMAILS). Shouldn't
this be part of HACKING or in the ./doc/programmer/design/ directory someplace.
    I would argue that exposing all cross-file functions as part of the API, no
matter how low level they are, isn't design so much as accretion.

What I'd suggest is that the existing/patched svn_subst_keywords_differ()
becomes svn_subst__keywords_differ() and a shim with the original name wraps it
(with the appropriate pool creation/destruction). Would this be appropriate?
The wrapper function could then be marked for deprecation in 2.x.

Thanks

John

-- 
John Peacock
Director of Information Research and Technology
Rowman & Littlefield Publishing Group
4501 Forbes Boulevard
Suite H
Lanham, MD  20706
301-459-3366 x.5010
fax 301-429-5748
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org