Return-Path: 
 <dev-return-8791-apmail-subversion-dev-archive=subversion.apache.org@subversion.apache.org>
Delivered-To: apmail-subversion-dev-archive@minotaur.apache.org
Received: (qmail 28629 invoked from network); 5 Jan 2011 12:44:38 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3)
  by minotaur.apache.org with SMTP; 5 Jan 2011 12:44:38 -0000
Received: (qmail 51887 invoked by uid 500); 5 Jan 2011 12:44:38 -0000
Delivered-To: apmail-subversion-dev-archive@subversion.apache.org
Received: (qmail 51764 invoked by uid 500); 5 Jan 2011 12:44:37 -0000
Mailing-List: contact dev-help@subversion.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:dev-help@subversion.apache.org>
List-Unsubscribe: <mailto:dev-unsubscribe@subversion.apache.org>
List-Post: <mailto:dev@subversion.apache.org>
List-Id: <dev.subversion.apache.org>
Delivered-To: mailing list dev@subversion.apache.org
Received: (qmail 51756 invoked by uid 99); 5 Jan 2011 12:44:37 -0000
Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230)
    by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 05 Jan 2011 12:44:37 +0000
X-ASF-Spam-Status: No, hits=0.7 required=10.0
	tests=SPF_NEUTRAL
X-Spam-Check-By: apache.org
Received-SPF: neutral (nike.apache.org: local policy)
Received: from [90.155.4.51] (HELO auth.a.painless.aaisp.net.uk) (90.155.4.51)
    by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 05 Jan 2011 12:44:28 +0000
Received: from 120.20.169.217.in-addr.arpa ([217.169.20.120]
 helo=[192.168.1.3])
	by a.painless.aaisp.net.uk with esmtpsa (TLSv1:AES256-SHA:256)
	(Exim 4.72)
	(envelope-from <julianfoad@btopenworld.com>)
	id 1PaSii-0000Qa-GU; Wed, 05 Jan 2011 12:44:04 +0000
Subject: RE: Any idea why public function like "svn_fspath__dirname" have
 double "__" in its name?
From: Julian Foad <julianfoad@btopenworld.com>
To: Kamesh Jayachandran <kamesh@collab.net>
Cc: Peter Samuelson <peter@p12n.org>, Michael Pilato <cmpilato@collab.net>,
  dev@subversion.apache.org
In-Reply-To: 
 <0213965108DEAD48960CE83455E07DFF0192BD9D@maa-exchmb.maa.corp.collab.net>
References: <4D19AE1C.30308@collab.net> <4D1A0500.8090900@collab.net>
	 <20101228221304.GQ13615@p12n.org>
	 <0213965108DEAD48960CE83455E07DFF0192BD9D@maa-exchmb.maa.corp.collab.net>
Content-Type: text/plain; charset="UTF-8"
Date: Wed, 05 Jan 2011 12:43:58 +0000
Message-ID: <1294231438.18270.101.camel@edith>
Mime-Version: 1.0
X-Mailer: Evolution 2.28.3 
Content-Transfer-Encoding: 7bit
X-Virus-Checked: Checked by ClamAV on apache.org

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