On Sat, Jun 21, 2014 at 8:23 PM, Branko Čibej <brane_at_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.
Received on 2015-03-05 15:13:20 CET