From c05a55b056509d1146ab55ab1351298789f00751 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Mart=C3=ADn=20Nieto?= Date: Tue, 23 Jul 2013 09:40:19 +0200 Subject: [PATCH 1/2] Clean up some documentation clang's docparser highlighted these. --- include/git2/notes.h | 4 ++-- include/git2/pack.h | 4 ++-- include/git2/sys/index.h | 2 -- include/git2/sys/refs.h | 4 ++-- include/git2/transport.h | 2 +- src/fileops.h | 8 ++++---- src/path.h | 2 -- src/pqueue.h | 6 ++---- 8 files changed, 13 insertions(+), 19 deletions(-) diff --git a/include/git2/notes.h b/include/git2/notes.h index 7382904ad..76361633b 100644 --- a/include/git2/notes.h +++ b/include/git2/notes.h @@ -99,7 +99,7 @@ GIT_EXTERN(int) git_note_read( /** * Get the note message * - * @param note + * @param note the note * @return the note message */ GIT_EXTERN(const char *) git_note_message(const git_note *note); @@ -108,7 +108,7 @@ GIT_EXTERN(const char *) git_note_message(const git_note *note); /** * Get the note object OID * - * @param note + * @param note the note * @return the note object OID */ GIT_EXTERN(const git_oid *) git_note_oid(const git_note *note); diff --git a/include/git2/pack.h b/include/git2/pack.h index cc1f48add..976e39cb4 100644 --- a/include/git2/pack.h +++ b/include/git2/pack.h @@ -137,7 +137,7 @@ GIT_EXTERN(int) git_packbuilder_foreach(git_packbuilder *pb, git_packbuilder_for * Get the total number of objects the packbuilder will write out * * @param pb the packbuilder - * @return + * @return the number of objects in the packfile */ GIT_EXTERN(uint32_t) git_packbuilder_object_count(git_packbuilder *pb); @@ -145,7 +145,7 @@ GIT_EXTERN(uint32_t) git_packbuilder_object_count(git_packbuilder *pb); * Get the number of objects the packbuilder has already written out * * @param pb the packbuilder - * @return + * @return the number of objects which have already been written */ GIT_EXTERN(uint32_t) git_packbuilder_written(git_packbuilder *pb); diff --git a/include/git2/sys/index.h b/include/git2/sys/index.h index a32e07036..1a06a4df1 100644 --- a/include/git2/sys/index.h +++ b/include/git2/sys/index.h @@ -72,7 +72,6 @@ GIT_EXTERN(int) git_index_name_add(git_index *index, * Remove all filename conflict entries. * * @param index an existing index object - * @return 0 or an error code */ GIT_EXTERN(void) git_index_name_clear(git_index *index); @@ -168,7 +167,6 @@ GIT_EXTERN(int) git_index_reuc_remove(git_index *index, size_t n); * Remove all resolve undo entries from the index * * @param index an existing index object - * @return 0 or an error code */ GIT_EXTERN(void) git_index_reuc_clear(git_index *index); diff --git a/include/git2/sys/refs.h b/include/git2/sys/refs.h index 85963258c..dd95ca12c 100644 --- a/include/git2/sys/refs.h +++ b/include/git2/sys/refs.h @@ -16,7 +16,7 @@ * * @param name the reference name * @param oid the object id for a direct reference - * @param symbolic the target for a symbolic reference + * @param peel the first non-tag object's OID, or NULL * @return the created git_reference or NULL on error */ GIT_EXTERN(git_reference *) git_reference__alloc( @@ -28,7 +28,7 @@ GIT_EXTERN(git_reference *) git_reference__alloc( * Create a new symbolic reference. * * @param name the reference name - * @param symbolic the target for a symbolic reference + * @param target the target for a symbolic reference * @return the created git_reference or NULL on error */ GIT_EXTERN(git_reference *) git_reference__alloc_symbolic( diff --git a/include/git2/transport.h b/include/git2/transport.h index 21061fc78..1cc200eb4 100644 --- a/include/git2/transport.h +++ b/include/git2/transport.h @@ -110,7 +110,7 @@ GIT_EXTERN(int) git_cred_ssh_keyfile_passphrase_new( * @param out The newly created credential object. * @param publickey The bytes of the public key. * @param publickey_len The length of the public key in bytes. - * @param sign_callback The callback method for authenticating. + * @param sign_fn The callback method for authenticating. * @param sign_data The abstract data sent to the sign_callback method. * @return 0 for success or an error code for failure */ diff --git a/src/fileops.h b/src/fileops.h index d23ebaffb..5adedfc57 100644 --- a/src/fileops.h +++ b/src/fileops.h @@ -244,7 +244,7 @@ extern mode_t git_futils_canonical_mode(mode_t raw_mode); * @param out buffer to populate with the mapping information. * @param fd open descriptor to configure the mapping from. * @param begin first byte to map, this should be page aligned. - * @param end number of bytes to map. + * @param len number of bytes to map. * @return * - 0 on success; * - -1 on error. @@ -278,7 +278,7 @@ extern void git_futils_mmap_free(git_map *map); /** * Find a "global" file (i.e. one in a user's home directory). * - * @param pathbuf buffer to write the full path into + * @param path buffer to write the full path into * @param filename name of file to find in the home directory * @return 0 if found, GIT_ENOTFOUND if not found, or -1 on other OS error */ @@ -287,7 +287,7 @@ extern int git_futils_find_global_file(git_buf *path, const char *filename); /** * Find an "XDG" file (i.e. one in user's XDG config path). * - * @param pathbuf buffer to write the full path into + * @param path buffer to write the full path into * @param filename name of file to find in the home directory * @return 0 if found, GIT_ENOTFOUND if not found, or -1 on other OS error */ @@ -296,7 +296,7 @@ extern int git_futils_find_xdg_file(git_buf *path, const char *filename); /** * Find a "system" file (i.e. one shared for all users of the system). * - * @param pathbuf buffer to write the full path into + * @param path buffer to write the full path into * @param filename name of file to find in the home directory * @return 0 if found, GIT_ENOTFOUND if not found, or -1 on other OS error */ diff --git a/src/path.h b/src/path.h index ead4fa338..b2899e97f 100644 --- a/src/path.h +++ b/src/path.h @@ -175,7 +175,6 @@ extern bool git_path_contains(git_buf *dir, const char *item); * * @param parent Directory path that might contain subdir * @param subdir Subdirectory name to look for in parent - * @param append_if_exists If true, then subdir will be appended to the parent path if it does exist * @return true if subdirectory exists, false otherwise. */ extern bool git_path_contains_dir(git_buf *parent, const char *subdir); @@ -185,7 +184,6 @@ extern bool git_path_contains_dir(git_buf *parent, const char *subdir); * * @param dir Directory path that might contain file * @param file File name to look for in parent - * @param append_if_exists If true, then file will be appended to the path if it does exist * @return true if file exists, false otherwise. */ extern bool git_path_contains_file(git_buf *dir, const char *file); diff --git a/src/pqueue.h b/src/pqueue.h index ed7139285..9061f8279 100644 --- a/src/pqueue.h +++ b/src/pqueue.h @@ -48,7 +48,7 @@ typedef struct { * should be preallocated * @param cmppri the callback function to compare two nodes of the queue * - * @Return the handle or NULL for insufficent memory + * @return the handle or NULL for insufficent memory */ int git_pqueue_init(git_pqueue *q, size_t n, git_pqueue_cmp cmppri); @@ -83,8 +83,7 @@ int git_pqueue_insert(git_pqueue *q, void *d); /** * pop the highest-ranking item from the queue. - * @param p the queue - * @param d where to copy the entry to + * @param q the queue * @return NULL on error, otherwise the entry */ void *git_pqueue_pop(git_pqueue *q); @@ -93,7 +92,6 @@ void *git_pqueue_pop(git_pqueue *q); /** * access highest-ranking item without removing it. * @param q the queue - * @param d the entry * @return NULL on error, otherwise the entry */ void *git_pqueue_peek(git_pqueue *q); From 64061d4a14f77fdcf6ecc038ea6e9b02f14e03a8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Mart=C3=ADn=20Nieto?= Date: Tue, 23 Jul 2013 10:51:14 +0200 Subject: [PATCH 2/2] remote: fix git_remote_download() documentation The description of what the function does hasn't been true for quite a while. Change it to reflect the way it currently works. While here, remove an even older comment about missing features that have been implemented. --- include/git2/remote.h | 20 +++++++------------- 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/include/git2/remote.h b/include/git2/remote.h index 13b04367c..fa8b378c6 100644 --- a/include/git2/remote.h +++ b/include/git2/remote.h @@ -25,13 +25,6 @@ GIT_BEGIN_DECL typedef int (*git_remote_rename_problem_cb)(const char *problematic_refspec, void *payload); -/* - * TODO: This functions still need to be implemented: - * - _listcb/_foreach - * - _add - * - _rename - * - _del (needs support from config) - */ /** * Add a remote with the default fetch refspec to the repository's configuration. This @@ -255,13 +248,14 @@ GIT_EXTERN(int) git_remote_connect(git_remote *remote, git_direction direction); GIT_EXTERN(int) git_remote_ls(git_remote *remote, git_headlist_cb list_cb, void *payload); /** - * Download the packfile + * Download and index the packfile * - * Negotiate what objects should be downloaded and download the - * packfile with those objects. The packfile is downloaded with a - * temporary filename, as it's final name is not known yet. If there - * was no packfile needed (all the objects were available locally), - * filename will be NULL and the function will return success. + * Connect to the remote if it hasn't been done yet, negotiate with + * the remote git which objects are missing, download and index the + * packfile. + * + * The .idx file will be created and both it and the packfile with be + * renamed to their final name. * * @param remote the remote to download from * @param progress_cb function to call with progress information. Be aware that