Update giterr_last API documentation to reflect real behaviour

include/git2/errors.h

@@ -109,7 +109,12 @@ typedef enum {
 
 /**
  * Return the last `git_error` object that was generated for the
- * current thread or NULL if no error has occurred.
+ * current thread.
+ *
+ * The default behaviour of this function is to return NULL if no previous error has occurred.
+ * However, libgit2's error strings are not cleared aggressively, so a prior
+ * (unrelated) error may be returned. This can avoided by only calling
+ * this function if the prior call to a libgit2 API returned an error.
  *
  * @return A git_error object.
  */