refs: document need to free refs in foreach-callback

References passed to the callback function of `git_reference_foreach`
are expected to be owned by the callback. As such, they are never being
freed by `git_reference_foreach`, but will have to be freed by the
caller. This small detail is never mentioned in the function's
documentation, though, making it easy to get wrong. Document this to
make it discoverable.

Author: pks-t

include/git2/refs.h

@@ -433,6 +433,9 @@ typedef int (*git_reference_foreach_name_cb)(const char *name, void *payload);
  * passed to this method.  Returning a non-zero value from the callback
  * will terminate the iteration.
  *
+ * Note that the callback function is responsible to call `git_reference_free`
+ * on each reference passed to it.
+ *
  * @param repo Repository where to find the refs
  * @param callback Function which will be called for every listed ref
  * @param payload Additional data to pass to the callback