[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

RE: Any idea why public function like "svn_fspath__dirname" have double "__" in its name?

From: Julian Foad <julianfoad_at_btopenworld.com>
Date: Wed, 05 Jan 2011 12:43:58 +0000

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
Received on 2011-01-05 13:44:46 CET

This is an archived mail posted to the Subversion Dev mailing list.