GNOME.org
 

[libgit2-glib] ggit-repository.c: Fix return annotations

commit 28cd78b178ca5dd54c786d6ec5fede33677ba1ca
Author: Brian C. Lane <bcl redhat com>
Date:   Wed Aug 30 10:42:05 2017 -0700

    ggit-repository.c: Fix return annotations
    
    Most of this is adding (allow-none) so that haskell-gi will pick it up
    and use a Maybe for the return type.

 libgit2-glib/ggit-repository.c |  118 +++++++++++++++++++++-------------------
 1 files changed, 61 insertions(+), 57 deletions(-)
---
diff --git a/libgit2-glib/ggit-repository.c b/libgit2-glib/ggit-repository.c
index f310844..25b6c54 100644
--- a/libgit2-glib/ggit-repository.c
+++ b/libgit2-glib/ggit-repository.c
@@ -540,7 +540,7 @@ _ggit_repository_get_repository (GgitRepository *repository)
  *     The method will automatically detect if @path is a normal
  *     or bare repository or fail if it is neither.
  *
- * Returns: (transfer full): a newly created #GgitRepository.
+ * Returns: (transfer full) (nullable): a newly created #GgitRepository.
  */
 GgitRepository *
 ggit_repository_open (GFile   *location,
@@ -564,7 +564,7 @@ ggit_repository_open (GFile   *location,
  *
  * Creates a new git repository in the given folder.
  *
- * Returns: (transfer full): a newly created #GgitRepository.
+ * Returns: (transfer full) (nullable): a newly created #GgitRepository.
  */
 GgitRepository *
 ggit_repository_init_repository (GFile     *location,
@@ -590,7 +590,7 @@ ggit_repository_init_repository (GFile     *location,
  *
  * Clones a new git repository in the given folder.
  *
- * Returns: (transfer full): a newly created #GgitRepository.
+ * Returns: (transfer full) (nullable): a newly created #GgitRepository.
  */
 GgitRepository *
 ggit_repository_clone (const gchar       *url,
@@ -625,7 +625,7 @@ ggit_repository_clone (const gchar       *url,
  * The special value %G_TYPE_NONE may be passed to let
  * the method guess the object's type.
  *
- * Returns: (transfer full): the found #GgitObject, or %NULL on error.
+ * Returns: (transfer full) (nullable): the found #GgitObject, or %NULL on error.
  */
 GgitObject *
 ggit_repository_lookup (GgitRepository  *repository,
@@ -671,7 +671,7 @@ ggit_repository_lookup (GgitRepository  *repository,
  * or the documentation for `git rev-parse` for information on the syntax
  * accepted.
  *
- * Returns: (transfer full): a #GgitObject or %NULL if the revision could not be found.
+ * Returns: (transfer full) (nullable): a #GgitObject or %NULL if the revision could not be found.
  *
  **/
 GgitObject *
@@ -709,7 +709,7 @@ ggit_repository_revparse (GgitRepository  *repository,
  * Lookups a reference by its name in @repository. The returned #GgitRef must
  * be freed with g_object_unref().
  *
- * Returns: (transfer full): the searched reference.
+ * Returns: (transfer full) (nullable): the searched reference.
  */
 GgitRef *
 ggit_repository_lookup_reference (GgitRepository  *repository,
@@ -748,7 +748,7 @@ ggit_repository_lookup_reference (GgitRepository  *repository,
  * rules to the given shorthand to determine which reference the user is referring to.
  * The returned #GgitRef must be freed with g_object_unref().
  *
- * Returns: (transfer full): the searched reference.
+ * Returns: (transfer full) (nullable): the searched reference.
  */
 GgitRef *
 ggit_repository_lookup_reference_dwim (GgitRepository  *repository,
@@ -790,7 +790,7 @@ ggit_repository_lookup_reference_dwim (GgitRepository  *repository,
  * The reference will be created in the repository and written
  * to the disk. The returned value must be freed with g_object_unref().
  *
- * Returns: (transfer full): the newly created reference.
+ * Returns: (transfer full) (nullable): the newly created reference.
  */
 GgitRef *
 ggit_repository_create_reference (GgitRepository  *repository,
@@ -838,7 +838,7 @@ ggit_repository_create_reference (GgitRepository  *repository,
  * The reference will be created in the repository and written
  * to the disk. The returned value must be freed with g_object_unref().
  *
- * Returns: (transfer full): the newly created reference.
+ * Returns: (transfer full) (nullable): the newly created reference.
  */
 GgitRef *
 ggit_repository_create_symbolic_reference (GgitRepository  *repository,
@@ -883,7 +883,7 @@ ggit_repository_create_symbolic_reference (GgitRepository  *repository,
  * retrieve the symbolic ref called HEAD, then use #ggit_repository_lookup_reference
  * instead.
  *
- * Returns: (transfer full): a #GgitRef
+ * Returns: (transfer full) (nullable): a #GgitRef
  *
  **/
 GgitRef *
@@ -952,7 +952,7 @@ ggit_repository_set_head (GgitRepository   *repository,
  * The lookup starts from @path and walks up the parent directories
  * and stops when a repository is found.
  *
- * Returns: (transfer full): the repository location.
+ * Returns: (transfer full) (nullable): the repository location.
  */
 GFile *
 ggit_repository_discover (GFile   *location,
@@ -977,7 +977,7 @@ ggit_repository_discover (GFile   *location,
  * The lookup starts from @path and walks up the parent directories
  * and stops when a repository is found.
  *
- * Returns: (transfer full): the repository location.
+ * Returns: (transfer full) (nullable): the repository location.
  */
 GFile *
 ggit_repository_discover_full (GFile        *location,
@@ -1122,7 +1122,7 @@ ggit_repository_is_empty (GgitRepository  *repository,
  *
  * Get the gitdir location of the repository.
  *
- * Returns: (transfer full): the location of the gitdir of the repository.
+ * Returns: (transfer full) (nullable): the location of the gitdir of the repository.
  */
 GFile *
 ggit_repository_get_location (GgitRepository *repository)
@@ -1142,7 +1142,7 @@ ggit_repository_get_location (GgitRepository *repository)
  *
  * Gets the working directory of the repository.
  *
- * Returns: (transfer full): the location of the working directory of the repository.
+ * Returns: (transfer full) (nullable): the location of the working directory of the repository.
  */
 GFile *
 ggit_repository_get_workdir (GgitRepository *repository)
@@ -1391,7 +1391,7 @@ ggit_repository_references_foreach_name (GgitRepository             *repository,
  *
  * Get the config for a specific repository.
  *
- * Returns: (transfer full): a #GgitConfig.
+ * Returns: (transfer full) (nullable): a #GgitConfig.
  *
  **/
 GgitConfig *
@@ -1423,7 +1423,7 @@ ggit_repository_get_config (GgitRepository  *repository,
  *
  * Get the index for a specific repository.
  *
- * Returns: (transfer full): a #GgitIndex.
+ * Returns: (transfer full) (nullable): a #GgitIndex.
  *
  **/
 GgitIndex *
@@ -1460,7 +1460,7 @@ ggit_repository_get_index (GgitRepository  *repository,
  *
  * Create a new tag object.
  *
- * Returns: (transfer full) (allow-none): the id to which the tag points, or
+ * Returns: (transfer full) (nullable): the id to which the tag points, or
  *                                        %NULL in case of an error.
  *
  **/
@@ -1513,7 +1513,7 @@ ggit_repository_create_tag (GgitRepository   *repository,
  * Create a new tag from a buffer describing the tag object. The buffer must
  * be correctly formatted.
  *
- * Returns: (transfer full) (allow-none): the id to which the tag points, or
+ * Returns: (transfer full) (nullable): the id to which the tag points, or
  *                                        %NULL in case of an error.
  *
  **/
@@ -1557,7 +1557,7 @@ ggit_repository_create_tag_from_buffer (GgitRepository   *repository,
  *
  * Creates a new lightweight tag.
  *
- * Returns: (transfer full) (allow-none): the id to which the tag points, or
+ * Returns: (transfer full) (nullable): the id to which the tag points, or
  *                                        %NULL in case of an error.
  *
  **/
@@ -1605,7 +1605,7 @@ ggit_repository_create_tag_lightweight (GgitRepository   *repository,
  *
  * Creates a new annotated tag.
  *
- * Returns: (transfer full) (allow-none): the id to which the tag points, or
+ * Returns: (transfer full) (nullable): the id to which the tag points, or
  *                                        %NULL in case of an error.
  *
  **/
@@ -1650,7 +1650,7 @@ ggit_repository_create_tag_annotation (GgitRepository  *repository,
  *
  * Fill a list with all the tags in the @repository.
  *
- * Returns: (transfer full) (allow-none): a list with the tags in @repository.
+ * Returns: (transfer full) (nullable): a list with the tags in @repository.
  **/
 gchar **
 ggit_repository_list_tags (GgitRepository  *repository,
@@ -1688,7 +1688,7 @@ ggit_repository_list_tags (GgitRepository  *repository,
  * Fill a list with all the tags in the @repository matching the provided
  * pattern. The pattern can use standard fnmatch syntax.
  *
- * Returns: (transfer full) (allow-none): a list with matching tags in @repository.
+ * Returns: (transfer full) (nullable): a list with matching tags in @repository.
  **/
 gchar **
 ggit_repository_list_tags_match (GgitRepository  *repository,
@@ -1829,7 +1829,7 @@ ggit_repository_tag_foreach (GgitRepository   *repository,
  *
  * Creates a new branch pointing at a target commit.
  *
- * Returns: (transfer full) (allow-none): the reference to which the branch
+ * Returns: (transfer full) (nullable): the reference to which the branch
  *                                        points, or %NULL in case of an error.
  **/
 GgitBranch *
@@ -1874,7 +1874,7 @@ ggit_repository_create_branch (GgitRepository   *repository,
  * Get a branch enumerator to enumerate over all branches of the specified
  * @list_type in @repository.
  *
- * Returns: (transfer full): a branch enumerator.
+ * Returns: (transfer full) (nullable): a branch enumerator.
  **/
 GgitBranchEnumerator *
 ggit_repository_enumerate_branches (GgitRepository  *repository,
@@ -1909,7 +1909,7 @@ ggit_repository_enumerate_branches (GgitRepository  *repository,
  *
  * Lookups a branch by its name in a repository.
  *
- * Returns: (transfer full) (allow-none): a branch by its name in a repository.
+ * Returns: (transfer full) (nullable): a branch by its name in a repository.
  */
 GgitBranch *
 ggit_repository_lookup_branch (GgitRepository *repository,
@@ -1946,7 +1946,7 @@ ggit_repository_lookup_branch (GgitRepository *repository,
  *
  * Lookups a branch by its name in a repository.
  *
- * Returns: (transfer full) (allow-none): a #GgitBlog pointer.
+ * Returns: (transfer full) (nullable): a #GgitBlog pointer.
  */
 GgitBlob *
 ggit_repository_lookup_blob (GgitRepository *repository,
@@ -1982,7 +1982,7 @@ ggit_repository_lookup_blob (GgitRepository *repository,
  *
  * Lookups a branch by its name in a repository.
  *
- * Returns: (transfer full) (allow-none): a #GgitCommit pointer.
+ * Returns: (transfer full) (nullable): a #GgitCommit pointer.
  */
 GgitCommit *
 ggit_repository_lookup_commit (GgitRepository *repository,
@@ -2018,7 +2018,7 @@ ggit_repository_lookup_commit (GgitRepository *repository,
  *
  * Lookups a branch by its name in a repository.
  *
- * Returns: (transfer full) (allow-none): a #GgitTag pointer.
+ * Returns: (transfer full) (nullable): a #GgitTag pointer.
  */
 GgitTag *
 ggit_repository_lookup_tag (GgitRepository *repository,
@@ -2054,7 +2054,7 @@ ggit_repository_lookup_tag (GgitRepository *repository,
  *
  * Lookups a branch by its name in a repository.
  *
- * Returns: (transfer full) (allow-none): a #GgitTree pointer.
+ * Returns: (transfer full) (nullable): a #GgitTree pointer.
  */
 GgitTree *
 ggit_repository_lookup_tree (GgitRepository *repository,
@@ -2090,7 +2090,7 @@ ggit_repository_lookup_tree (GgitRepository *repository,
  *
  * Gets the remote called @name.
  *
- * Returns: (transfer full) (allow-none): a new #GgitRemote or %NULL if there is an error.
+ * Returns: (transfer full) (nullable): a new #GgitRemote or %NULL if there is an error.
  */
 GgitRemote *
 ggit_repository_lookup_remote (GgitRepository  *repository,
@@ -2126,7 +2126,7 @@ ggit_repository_lookup_remote (GgitRepository  *repository,
  *
  * Adds a remote with the default fetch refspec to the repository's configuration.
  *
- * Returns: (transfer full) (allow-none): a new #GgitRemote or %NULL if there is an error.
+ * Returns: (transfer full) (nullable): a new #GgitRemote or %NULL if there is an error.
  */
 GgitRemote *
 ggit_repository_create_remote (GgitRepository  *repository,
@@ -2162,7 +2162,7 @@ ggit_repository_create_remote (GgitRepository  *repository,
  *
  * Fill a list with all the remotes in @repository.
  *
- * Returns: (transfer full) (allow-none): a list with the remotes.
+ * Returns: (transfer full) (nullable): a list with the remotes.
  **/
 gchar **
 ggit_repository_list_remotes (GgitRepository  *repository,
@@ -2266,7 +2266,7 @@ ggit_repository_add_remote_fetch (GgitRepository  *repository,
  * Lookups a submodule information by name or path. If the submodule
  * does not exist, %NULL is returned and a GGIT_ERROR_NOTFOUND error set.
  *
- * Returns: (transfer full) (allow-none): a newly-allocated #GgitSubmodule.
+ * Returns: (transfer full) (nullable): a newly-allocated #GgitSubmodule.
  */
 GgitSubmodule *
 ggit_repository_lookup_submodule (GgitRepository  *repository,
@@ -2632,7 +2632,7 @@ ggit_repository_reset_default (GgitRepository       *repository,
  * It returns the commit containing the stashed state.
  * This commit is also the target of the direct reference refs/stash.
  *
- * Returns: (transfer full): a new object id of the commit containing the stashed state.
+ * Returns: (transfer full) (nullable): a new object id of the commit containing the stashed state.
  */
 GgitOId *
 ggit_repository_save_stash (GgitRepository  *repository,
@@ -2855,7 +2855,7 @@ ggit_repository_get_descendant_of (GgitRepository  *repository,
  * blob id can be obtained from the blob output stream using
  * #ggit_blob_output_stream_get_id, after you close the stream.
  *
- * Returns: (transfer full): a #GgitBlobOutputStream.
+ * Returns: (transfer full) (nullable): a #GgitBlobOutputStream.
  *
  **/
 GgitBlobOutputStream *
@@ -2874,8 +2874,8 @@ ggit_repository_create_blob (GgitRepository *repository)
  *
  * Write an in-memory buffer to the object database as a blob.
  *
- * Returns: the new #GgitOid of the written blob, or %NULL if writing the blob
- * failed.
+ * Returns: (transfer full) (nullable): the new #GgitOid of the written blob,
+ * or %NULL if writing the blob failed.
  */
 GgitOId *
 ggit_repository_create_blob_from_buffer (GgitRepository  *repository,
@@ -2912,8 +2912,8 @@ ggit_repository_create_blob_from_buffer (GgitRepository  *repository,
  *
  * Write a file to the object database as a blob.
  *
- * Returns: the new #GgitOid of the written blob, or %NULL if writing the blob
- * failed.
+ * Returns (transfer full) (nullable): the new #GgitOid of the written blob,
+ * or %NULL if writing the blob failed.
  */
 GgitOId *
 ggit_repository_create_blob_from_file (GgitRepository  *repository,
@@ -2954,8 +2954,8 @@ ggit_repository_create_blob_from_file (GgitRepository  *repository,
  * Write a path relative to the repository working directory to the object
  * database as a blob.
  *
- * Returns: the new #GgitOid of the written blob, or %NULL if writing the blob
- * failed.
+ * Returns: (transfer full) (nullable): the new #GgitOid of the written blob,
+ * or %NULL if writing the blob failed.
  */
 GgitOId *
 ggit_repository_create_blob_from_path (GgitRepository  *repository,
@@ -3003,7 +3003,8 @@ ggit_repository_create_blob_from_path (GgitRepository  *repository,
  * provided @message. Note that @message will not be cleaned up automatically.
  * You can use #ggit_message_prettify to do this yourself if needed.
  *
- * Returns: the #GgitOId of the created commit object, or %NULL in case of an error.
+ * Returns: (transfer full) (nullable): the #GgitOId of the created commit object,
+ * or %NULL in case of an error.
  *
  */
 GgitOId *
@@ -3073,7 +3074,8 @@ ggit_repository_create_commit (GgitRepository  *repository,
  * provided @message. Note that @message will not be cleaned up automatically.
  * You can use #ggit_message_prettify to do this yourself if needed.
  *
- * Returns: the #GgitOId of the created commit object, or %NULL in case of an error.
+ * Returns: (transfer full) (nullable): the #GgitOId of the created commit object,
+ * or %NULL in case of an error.
  *
  */
 GgitOId *
@@ -3129,7 +3131,8 @@ ggit_repository_create_commit_from_ids (GgitRepository  *repository,
  *
  * Create a new tree builder.
  *
- * Returns: (transfer full): a new #GgitTreeBuilder, or %NULL if there was an error.
+ * Returns: (transfer full) (nullable): a new #GgitTreeBuilder,
+ * or %NULL if there was an error.
  **/
 GgitTreeBuilder *
 ggit_repository_create_tree_builder (GgitRepository  *repository,
@@ -3161,7 +3164,8 @@ ggit_repository_create_tree_builder (GgitRepository  *repository,
  * Create a tree builder for initialized with @tree. To create an empty
  * tree builder, use #ggit_repository_create_tree_builder instead.
  *
- * Returns: (transfer full): a new #GgitTreeBuilder object, or %NULL if there was an error.
+ * Returns: (transfer full) (nullable): a new #GgitTreeBuilder object,
+ * or %NULL if there was an error.
  **/
 GgitTreeBuilder *
 ggit_repository_create_tree_builder_from_tree (GgitRepository  *repository,
@@ -3205,7 +3209,7 @@ ggit_repository_create_tree_builder_from_tree (GgitRepository  *repository,
  * (see #ggit_index_entry_get_id) which could point to a blob (for a file)
  * or a tree (for a directory).
  *
- * Returns: a #GgitIndexEntry or %NULL when an error occurred.
+ * Returns: (transfer full) (nullable): a #GgitIndexEntry or %NULL when an error occurred.
  *
  **/
 GgitIndexEntry *
@@ -3268,7 +3272,7 @@ ggit_repository_create_index_entry_for_file (GgitRepository  *repository,
  * (see #ggit_index_entry_get_id) which could point to a blob (for a file)
  * or a tree (for a directory).
  *
- * Returns: a #GgitIndexEntry or %NULL when an error occurred.
+ * Returns: (transfer full) (nullable): a #GgitIndexEntry or %NULL when an error occurred.
  *
  **/
 GgitIndexEntry *
@@ -3321,7 +3325,7 @@ ggit_repository_create_index_entry_for_path (GgitRepository  *repository,
  *
  * Get a blame for a single file.
  *
- * Returns: (transfer full): a #GgitBlame.
+ * Returns: (transfer full) (nullable): a #GgitBlame.
  *
  **/
 GgitBlame *
@@ -3369,7 +3373,7 @@ ggit_repository_blame_file (GgitRepository    *repository,
  *
  * Get the attribute value of the specified attribute for the given file.
  *
- * Returns: the attribute value, or %NULL.
+ * Returns: (transfer none) (nullable): the attribute value, or %NULL.
  *
  **/
 const gchar *
@@ -3611,7 +3615,7 @@ ggit_repository_cherry_pick (GgitRepository         *repository,
  * Cherry-picks the given @commit against the provided @our_commit, producing
  * and index that reflects the result of the cherry-pick.
  *
- * Returns: (transfer full): a #GgitIndex.
+ * Returns: (transfer full) (nullable): a #GgitIndex.
  *
  **/
 GgitIndex *
@@ -3654,7 +3658,7 @@ ggit_repository_cherry_pick_commit (GgitRepository    *repository,
  * Gets the default notes reference for @repository. It defaults to
  * "refs/notes/commits".
  *
- * Returns: (transfer full): the default notes reference for @repository.
+ * Returns: (transfer full) (nullable): the default notes reference for @repository.
  */
 gchar *
 ggit_repository_get_default_notes_ref (GgitRepository  *repository,
@@ -3694,7 +3698,7 @@ ggit_repository_get_default_notes_ref (GgitRepository  *repository,
  *
  * Adds a note for an object.
  *
- * Returns: (transfer full): the OID for the note or %NULL in case of error.
+ * Returns: (transfer full) (nullable): the OID for the note or %NULL in case of error.
  */
 GgitOId *
 ggit_repository_create_note (GgitRepository  *repository,
@@ -3787,7 +3791,7 @@ ggit_repository_remove_note (GgitRepository  *repository,
  *
  * Reads the note for an object.
  *
- * Returns: (transfer full): the read note or %NULL in case of an error.
+ * Returns: (transfer full) (nullable): the read note or %NULL in case of an error.
  */
 GgitNote *
 ggit_repository_read_note (GgitRepository  *repository,
@@ -3900,7 +3904,7 @@ ggit_repository_note_foreach (GgitRepository    *repository,
  *
  * Merge two trees creating a #GgitIndex reflecting the result of the merge.
  *
- * Returns: (transfer full): a new #GgitIndex or %NULL if an error occurred.
+ * Returns: (transfer full) (nullable): a new #GgitIndex or %NULL if an error occurred.
  *
  **/
 GgitIndex *
@@ -3946,7 +3950,7 @@ ggit_repository_merge_trees (GgitRepository    *repository,
  *
  * Merge two commits creating a #GgitIndex reflecting the result of the merge.
  *
- * Returns: (transfer full): a new #GgitIndex or %NULL if an error occurred.
+ * Returns: (transfer full) (nullable): a new #GgitIndex or %NULL if an error occurred.
  *
  **/
 GgitIndex *
@@ -3996,7 +4000,7 @@ ggit_repository_merge_commits (GgitRepository    *repository,
  * process, call git_rebase_next(). When you have finished with this
  * object, call g_object_unref().
  *
- * Returns: (transfer full): a newly allocated #GgitRebase.
+ * Returns: (transfer full) (nullable): a newly allocated #GgitRebase.
  */
 GgitRebase *
 ggit_repository_rebase_init (GgitRepository       *repository,
@@ -4037,7 +4041,7 @@ ggit_repository_rebase_init (GgitRepository       *repository,
  * Opens an existing rebase that was previously started by either an
  * invocation of ggit_rebase_init() or by another client.
  *
- * Returns: (transfer full): a newly allocated #GgitRebase.
+ * Returns: (transfer full) (nullable): a newly allocated #GgitRebase.
  */
 GgitRebase *
 ggit_repository_rebase_open (GgitRepository     *repository,
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]