diff options
Diffstat (limited to 'include/git2/signature.h')
| -rw-r--r-- | include/git2/signature.h | 35 |
1 files changed, 23 insertions, 12 deletions
diff --git a/include/git2/signature.h b/include/git2/signature.h index cbf94269f..00d19de66 100644 --- a/include/git2/signature.h +++ b/include/git2/signature.h @@ -1,5 +1,5 @@ /* - * Copyright (C) 2009-2012 the libgit2 contributors + * Copyright (C) the libgit2 contributors. All rights reserved. * * This file is part of libgit2, distributed under the GNU GPL v2 with * a Linking Exception. For full terms see the included COPYING file. @@ -20,41 +20,52 @@ GIT_BEGIN_DECL /** - * Create a new action signature. The signature must be freed - * manually or using git_signature_free + * Create a new action signature. * - * @param sig_out new signature, in case of error NULL + * Call `git_signature_free()` to free the data. + * + * Note: angle brackets ('<' and '>') characters are not allowed + * to be used in either the `name` or the `email` parameter. + * + * @param out new signature, in case of error NULL * @param name name of the person * @param email email of the person * @param time time when the action happened * @param offset timezone offset in minutes for the time * @return 0 or an error code */ -GIT_EXTERN(int) git_signature_new(git_signature **sig_out, const char *name, const char *email, git_time_t time, int offset); +GIT_EXTERN(int) git_signature_new(git_signature **out, const char *name, const char *email, git_time_t time, int offset); /** - * Create a new action signature with a timestamp of 'now'. The - * signature must be freed manually or using git_signature_free + * Create a new action signature with a timestamp of 'now'. + * + * Call `git_signature_free()` to free the data. * - * @param sig_out new signature, in case of error NULL + * @param out new signature, in case of error NULL * @param name name of the person * @param email email of the person * @return 0 or an error code */ -GIT_EXTERN(int) git_signature_now(git_signature **sig_out, const char *name, const char *email); +GIT_EXTERN(int) git_signature_now(git_signature **out, const char *name, const char *email); /** - * Create a copy of an existing signature. + * Create a copy of an existing signature. All internal strings are also + * duplicated. + * + * Call `git_signature_free()` to free the data. * - * All internal strings are also duplicated. * @param sig signature to duplicated * @return a copy of sig, NULL on out of memory */ GIT_EXTERN(git_signature *) git_signature_dup(const git_signature *sig); /** - * Free an existing signature + * Free an existing signature. + * + * Because the signature is not an opaque structure, it is legal to free it + * manually, but be sure to free the "name" and "email" strings in addition + * to the structure itself. * * @param sig signature to free */ |