kfogel@collab.net wrote:
> "Max Bowsher" <maxb@ukf.net> writes:
>> I don't believe we've ever defined *exactly* what the significance of
>> a double-underscore symbol name is.
>> Two of definitions I've heard of are:
>>
>> (a) anything that should not be used by users, but can we used at will
>> internally by the Subversion libraries.
>>
>> (b) symbols that should have visibility only to the library that they
>> are defined in, and should not be used *anywhere* outside that library.
>
> (b), and if that's not made clear enough in hacking.html, then we
> should fix the text. By "used", we mean "appear in the source code
> of", see below for why that distinction is important.
>
> Note that we sometime call svn__foo_* from C test code, but that's
> only because individual libraries don't have their own private test
> suites. As far as real code goes, only libsvn_foo should ever use
> svn__foo_*.
>
>> The double-underscore symbols which do not meet the strictest
>> definition are:
>>
>> svn_error__locate: used almost everywhere
>
> Mmm, sort of.
>
> It's present in the expansions of some svn_err_* macros, but that's
> okay. Those macros are in the correct space, and whatever they want
> to do is fine, because the macro would always be changed along with
> the internal implementation on which it depends.
A seperate sub-thread has arisen discussing ABI compat, so I won't say more
here.
>> svn_sort__hash: used by libsvn_client, mod_dav_svn, and svn
>
> This is a legacy problem, yes. It is a public function, appearing in
> a public header file, and it should be named accordingly. However,
> its doc string says:
>
> * @note Private. For use by Subversion's own code only. See issue #1644.
> *
> * @note This function and the @c svn_sort__item_t should go over to APR.
>
> Issue #1644 is closed now, and I don't feel any driving urge to move
> that function over to APR, so we should just rename it and leave the
> old name as an alias (perhaps using a macro?).
Nope, can't be a macro - ABI compat, again.
>> svn_{fs,ra}_foo__init: linked into the loader libs
>
> Yes, why aren't these public and single-underscore? If there's some
> circular dependency reason, it's okay, we can leave the current
> situation as it is (since the problem is unlikely to grow very much),
> but we should at least have a comment by those declarations explaining
> what
> is going on.
These are odd. They are very definitely NOT public, as their API is
partially mutable, but they are also explicitly intended for cross-library
use.
>> svn_txdelta__apply_instructions, svn_txdelta__compose_windows: used by
>> the fs backends
>
> Badness. They should be public, single-underscore functions, just as
> recommended above for svn_sort__hash().
I agree on this.
Max.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Wed Oct 5 00:42:18 2005