subversion-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Julian Foad <julianf...@btopenworld.com>
Subject RE: Any idea why public function like "svn_fspath__dirname" have double "__" in its name?
Date Wed, 05 Jan 2011 12:43:58 GMT
On Thu, 2010-12-30, Kamesh Jayachandran wrote:
> >> While we've mandated that "__" must be used for semi-public
> >> functions, we've never said that it can't be used for private ones.
> 
> >Kamesh is talking about public, not private, functions.  I.e., ones
> >where we actually do have an ABI promise to keep.
> 
> >I looked at svn_error__locate last week.  It's really only useful in
> >--enable-maintainer-mode, but the way it's implemented, it ends up
> >being used by macros in the public (non-maintainer) ABI, so even if we
> >eliminate those callers, we have to supply the function itself forever.
> >I've addressed this as best we can, in r1053469.
> 
> Thanks
> 
> >Supplying a given ABI forever is the sort of thing I thought we didn't
> >have to do for __ functions.  I think that's Kamesh's question too.
> 
> Yes. Following is my understanding, correct me if I am wrong.
> 
> <my understanding>
> Any function/macro inside the header *directly* under
> subversion/include should only have a public functions(ones that
> starts with svn_ and do *not* have __). 
> 
> If somebody differs from this convention then there should be
> *subversion dev* community independent convention here may be like
> these.
> 
> * doc string of such functions(semi-public a.k.a intra library
> functions/private(should we even have such one in headers?)) should
> promptly say so in the headers.
> 
> * start with __svn like we see in some of the libc headers. The vague
> __ starting would signal about the scope/ABI nature of the API.
> 
> </my understanding>

I added the svn_fspath__* functions.  My understanding and my intention
is:

  * The double underscore means this function is not for public use and
does not have compatibility guarantees even though it is physically
exported.

  * Functions that are not for public use should normally be in
'subversion/include/private/*.h'.  These functions are in
'subversion/include/svn_dirent_uri.h' because they are analogous to
other functions there, but we could move them.


> With regards
> Kamesh Jayachandran
> 
> [PS] Unless I am mistaken svn_fspath__* can be used in libsvn_repos
> too instead of svn_path_* wherever applicable and hence a chance to
> become public.

I don't quite understand what you mean here.

- Julian



Mime
View raw message