private functions in public api?

[Neels J Hofmeyr <ne...@elego.de>]

There are double-underscored function names in include/svn_dirent_uri.h (and
in other include/*.h, too), found both on trunk and on 1.7.x, as well as in
recent beta releases. Have our naming conventions changed??

[[[
> svn cat $svnrepos/tags/1.7.0-beta3/subversion/include/svn_dirent_uri.h |
grep [a-z]__[a-z]
 *    - @c svn_relpath__internal_style()
svn_relpath__internal_style(const char *relpath,
svn_uri__is_child(const char *parent_uri,
svn_relpath__is_child(const char *parent_relpath,
svn_relpath__is_ancestor(const char *parent_relpath,
svn_uri__is_ancestor(const char *parent_uri,
]]]

~Neels

Re: private functions in public api?

[Neels J Hofmeyr <ne...@elego.de>]

On 08/15/2011 10:52 AM, Julian Foad wrote:
> On Sun, 2011-08-14, Neels J Hofmeyr wrote:
>> There are double-underscored function names in include/svn_dirent_uri.h (and
>> in other include/*.h, too), found both on trunk and on 1.7.x, as well as in
>> recent beta releases. Have our naming conventions changed??
> 
> Such functions are unsupported even though they appear in a public
> header.  Oh, I see in
> <http://subversion.apache.org/docs/community-guide/conventions.html#other-conventions> we say that was the practice 'pre-Subversion 1.5' and not current practice.  A few such symbols have been introduced in each (minor) release.  The ones you pointed out here are ones I made private in the recent API review.  Since they are closely related to other functions that are public, it seemed to make sense to leave them there at the time I made them private, along with being less churn, as I wasn't sure whether they'd survive till 1.7.0 at all (but now they have).
> 
> I can move these into a private header if it's helpful.  Should I?

I'd personally find it helpful if I were a developer using SVN's API --
because I'd just think I can use all the functions that are there. (Then two
years later I'd read that '__' means 'not long term supported' and then I'd
understand why my code stopped working. -- "gah, why didn't they put it in a
*private* header if it's private!?")

But I don't have a concrete real case, so
+0

~Neels

> 
> (As a separate question, does anyone know whether the reasons are 'soft'
> such as tidiness or 'hard'?  I seem to recall a discussion in the
> distant past concerning a problem with symbols being exported into DLLs
> and becoming part of the ABI, but I don't recall the exact problem or
> the conclusion.)
> 
> - Julian
> 
> 
>> [[[
>>> svn cat $svnrepos/tags/1.7.0-beta3/subversion/include/svn_dirent_uri.h |
>> grep [a-z]__[a-z]
>>  *    - @c svn_relpath__internal_style()
>> svn_relpath__internal_style(const char *relpath,
>> svn_uri__is_child(const char *parent_uri,
>> svn_relpath__is_child(const char *parent_relpath,
>> svn_relpath__is_ancestor(const char *parent_relpath,
>> svn_uri__is_ancestor(const char *parent_uri,
>> ]]]
>>
>> ~Neels
> 
> 

Re: private functions in public api?

[Julian Foad <ju...@wandisco.com>]

On Sun, 2011-08-14, Neels J Hofmeyr wrote:
> There are double-underscored function names in include/svn_dirent_uri.h (and
> in other include/*.h, too), found both on trunk and on 1.7.x, as well as in
> recent beta releases. Have our naming conventions changed??

Such functions are unsupported even though they appear in a public
header.  Oh, I see in
<http://subversion.apache.org/docs/community-guide/conventions.html#other-conventions> we say that was the practice 'pre-Subversion 1.5' and not current practice.  A few such symbols have been introduced in each (minor) release.  The ones you pointed out here are ones I made private in the recent API review.  Since they are closely related to other functions that are public, it seemed to make sense to leave them there at the time I made them private, along with being less churn, as I wasn't sure whether they'd survive till 1.7.0 at all (but now they have).

I can move these into a private header if it's helpful.  Should I?

(As a separate question, does anyone know whether the reasons are 'soft'
such as tidiness or 'hard'?  I seem to recall a discussion in the
distant past concerning a problem with symbols being exported into DLLs
and becoming part of the ABI, but I don't recall the exact problem or
the conclusion.)

- Julian


> [[[
> > svn cat $svnrepos/tags/1.7.0-beta3/subversion/include/svn_dirent_uri.h |
> grep [a-z]__[a-z]
>  *    - @c svn_relpath__internal_style()
> svn_relpath__internal_style(const char *relpath,
> svn_uri__is_child(const char *parent_uri,
> svn_relpath__is_child(const char *parent_relpath,
> svn_relpath__is_ancestor(const char *parent_relpath,
> svn_uri__is_ancestor(const char *parent_uri,
> ]]]
> 
> ~Neels