"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.
> 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?).
> 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.
> 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().
Thoughts? Any objections to these assertions and solutions?
Thanks for pointing out these problems,
-Karl
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Tue Oct 4 22:17:55 2005