Update some documentation

include/git2/diff.h

@@ -421,7 +421,7 @@ typedef int (*git_diff_file_cb)(
 /**
  * Structure describing a hunk of a diff.
  */
-typedef struct git_diff_hunk {
+typedef struct {
 	int    old_start;     /**< Starting line number in old_file */
 	int    old_lines;     /**< Number of lines in old_file */
 	int    new_start;     /**< Starting line number in new_file */
@@ -468,7 +468,7 @@ typedef enum {
 /**
  * Structure describing a line (or data span) of a diff.
  */
-typedef struct git_diff_line {
+typedef struct {
 	char   origin;       /**< A git_diff_line_t value */
 	int    old_lineno;   /**< Line number in old file or -1 for added line */
 	int    new_lineno;   /**< Line number in new file or -1 for deleted line */

include/git2/net.h

@@ -32,9 +32,9 @@ typedef enum {
 	GIT_DIRECTION_PUSH  = 1
 } git_direction;
 
-
 /**
- * Remote head description, given out on `ls` calls.
+ * Description of a reference advertised by a remote server, given out
+ * on `ls` calls.
  */
 struct git_remote_head {
 	int local; /* available locally */

include/git2/revwalk.h

@@ -21,33 +21,38 @@
 GIT_BEGIN_DECL
 
 /**
+ * Flags to specify the sorting which a revwalk should perform.
+ */
+typedef enum {
+	/**
 	 * Sort the repository contents in no particular ordering;
 	 * this sorting is arbitrary, implementation-specific
 	 * and subject to change at any time.
 	 * This is the default sorting for new walkers.
 	 */
-#define GIT_SORT_NONE			(0)
+	GIT_SORT_NONE = 0,
 
-/**
+	/**
 	 * Sort the repository contents in topological order
 	 * (parents before children); this sorting mode
 	 * can be combined with time sorting.
 	 */
-#define GIT_SORT_TOPOLOGICAL (1 << 0)
+	GIT_SORT_TOPOLOGICAL = 1 << 0,
 
-/**
+	/**
 	 * Sort the repository contents by commit time;
 	 * this sorting mode can be combined with
 	 * topological sorting.
 	 */
-#define GIT_SORT_TIME			(1 << 1)
+	GIT_SORT_TIME = 1 << 1,
 
-/**
+	/**
 	 * Iterate through the repository contents in reverse
 	 * order; this sorting mode can be combined with
 	 * any of the above.
 	 */
-#define GIT_SORT_REVERSE		(1 << 2)
+	GIT_SORT_REVERSE = 1 << 2,
+} git_sort_t;
 
 /**
  * Allocate a new revision walker to iterate through a repo.

include/git2/types.h

@@ -209,10 +209,25 @@ typedef enum {
 	GIT_FILEMODE_COMMIT              = 0160000,
 } git_filemode_t;
 
+/*
+ * A refspec specifies the mapping between remote and local reference
+ * names when fetch or pushing.
+ */
 typedef struct git_refspec git_refspec;
+
+/**
+ * Git's idea of a remote repository. A remote can be anonymous (in
+ * which case it does not have backing configuration entires).
+ */
 typedef struct git_remote git_remote;
+
+/**
+ * Preparation for a push operation. Can be used to configure what to
+ * push and the level of parallelism of the packfile builder.
+ */
 typedef struct git_push git_push;
 
+/* documentation in the definition */
 typedef struct git_remote_head git_remote_head;
 typedef struct git_remote_callbacks git_remote_callbacks;