You are viewing a plain text version of this content. The canonical link for it is here.

Posted to dev@subversion.apache.org by Stefan Fuhrmann <st...@wandisco.com> on 2015/03/05 15:11:23 UTC

Re: 1.9 API review

On Sat, Jun 21, 2014 at 8:23 PM, Branko Čibej <br...@wandisco.com> wrote:

>  I've started a page on the Wiki for the pre-release API review. I guess
> I'm jumping the gun just a bit, but a couple days ago I noticed some
> missing bits in the docstrings of two functions, and though it better to
> just put this in the wiki instead of risking losing the thread on dev@.
>
> https://wiki.apache.org/subversion/Svn19ApiReview
>
>
I'm currently reviewing svn_fs.h and svn_repos.h.
There are a few common issues that I've noticed
and I'd like to fix them in the headers before putting
the non-trivial remainder into the wiki.

* New functions and function types should name
  their pool arguments scratch_pool or result_pool.
* We should mention the pool usage in the docstring
  for completeness.
* Similarly, docstrings should say whether / that
  notification callbacks may be NULL.

* Function references (e.g. in @see) should not
  have "()" attached to them - just to be consistent
  with what we do in most other places.
* A few function references are outdated, i.e. point
  to deprecated functions.

This all applies to new / rev'ed functions only. If nobody
objects, I'd simply change the two headers accordingly.

-- Stefan^2.

Re: 1.9 API review

Posted by Stefan Fuhrmann <st...@wandisco.com>.

On Mon, Mar 16, 2015 at 8:40 PM, Stefan Fuhrmann <
stefan.fuhrmann@wandisco.com> wrote:

>
>
> On Thu, Mar 5, 2015 at 3:11 PM, Stefan Fuhrmann <
> stefan.fuhrmann@wandisco.com> wrote:
>
>> On Sat, Jun 21, 2014 at 8:23 PM, Branko Čibej <br...@wandisco.com> wrote:
>>
>>>  I've started a page on the Wiki for the pre-release API review. I guess
>>> I'm jumping the gun just a bit, but a couple days ago I noticed some
>>> missing bits in the docstrings of two functions, and though it better to
>>> just put this in the wiki instead of risking losing the thread on dev@.
>>>
>>> https://wiki.apache.org/subversion/Svn19ApiReview
>>>
>>>
>> I'm currently reviewing svn_fs.h and svn_repos.h.
>> There are a few common issues that I've noticed
>> and I'd like to fix them in the headers before putting
>> the non-trivial remainder into the wiki.
>>
>
> Now that I'm reckoned amongst the living again,
> I completed the header updates. The remaining
> questions and suggested non-trivial changes are
> in the Wiki now. Please have a look.
>

All headers are now reviewed. The bits I couldn't fix
right away are document here:

https://wiki.apache.org/subversion/Svn19ApiReview

Please go through them and fix the parts that you know.

-- Stefan^2.

Re: 1.9 API review

Posted by Stefan Fuhrmann <st...@wandisco.com>.

On Thu, Mar 5, 2015 at 3:11 PM, Stefan Fuhrmann <
stefan.fuhrmann@wandisco.com> wrote:

> On Sat, Jun 21, 2014 at 8:23 PM, Branko Čibej <br...@wandisco.com> wrote:
>
>>  I've started a page on the Wiki for the pre-release API review. I guess
>> I'm jumping the gun just a bit, but a couple days ago I noticed some
>> missing bits in the docstrings of two functions, and though it better to
>> just put this in the wiki instead of risking losing the thread on dev@.
>>
>> https://wiki.apache.org/subversion/Svn19ApiReview
>>
>>
> I'm currently reviewing svn_fs.h and svn_repos.h.
> There are a few common issues that I've noticed
> and I'd like to fix them in the headers before putting
> the non-trivial remainder into the wiki.
>

Now that I'm reckoned amongst the living again,
I completed the header updates. The remaining
questions and suggested non-trivial changes are
in the Wiki now. Please have a look.

-- Stefan^2.

Re: 1.9 API review

Posted by Stefan Fuhrmann <st...@wandisco.com>.

On Thu, Mar 5, 2015 at 3:23 PM, Julian Foad <ju...@btopenworld.com>
wrote:

> Stefan Fuhrmann wrote:
> >I'm currently reviewing svn_fs.h and svn_repos.h.
> [...]
> > * Function references (e.g. in @see) should not
> >   have "()" attached to them - just to be consistent
> >   with what we do in most other places.
>
> I have adopted the practice of identifying functions with () in Doxygen
> doc strings because Doxygen recognizes that syntax and it's much neater
> than prefixing with '@c' or anything else. Inside '@see' Doxygen seems to
> assume (I'm only guessing) that every word is an identifier if it can find
> it, so the parentheses may be redundant in that particular context, but
> elsewhere they are valuable.
>

Ah, ok. I mostly noticed it in @see sections anyway,
so I'll only change it there.

-- Stefan^2.

Re: 1.9 API review

Posted by Julian Foad <ju...@btopenworld.com>.

Stefan Fuhrmann wrote:
>I'm currently reviewing svn_fs.h and svn_repos.h.
[...]
> * Function references (e.g. in @see) should not
>   have "()" attached to them - just to be consistent
>   with what we do in most other places.

I have adopted the practice of identifying functions with () in Doxygen doc strings because Doxygen recognizes that syntax and it's much neater than prefixing with '@c' or anything else. Inside '@see' Doxygen seems to assume (I'm only guessing) that every word is an identifier if it can find it, so the parentheses may be redundant in that particular context, but elsewhere they are valuable.

- Julian