Merge pull request #1745 from libgit2/doc-fixes

Doc fixes

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);

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);
 

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
+ *
+ * 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.
  *
- * 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.
+ * 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

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);
 

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(

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
  */

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
  */

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);

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);