Update some documentation

4 files changed, 47 insertions, 27 deletions

diff --git a/include/git2/diff.h b/include/git2/diff.h
index ca49a9cd9..1013b5c33 100644
--- a/include/git2/diff.h
+++ b/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 */
diff --git a/include/git2/net.h b/include/git2/net.h
index a727696a2..8cffa18dc 100644
--- a/include/git2/net.h
+++ b/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 */
diff --git a/include/git2/revwalk.h b/include/git2/revwalk.h
index 1bd6186f3..0a5fdce21 100644
--- a/include/git2/revwalk.h
+++ b/include/git2/revwalk.h
@@ -21,33 +21,38 @@
 GIT_BEGIN_DECL
 
 /**
- * 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.
+ * Flags to specify the sorting which a revwalk should perform.
  */
-#define GIT_SORT_NONE			(0)
+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.
+	 */
+	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)
+	/**
+	 * Sort the repository contents in topological order
+	 * (parents before children); this sorting mode
+	 * can be combined with time sorting.
+	 */
+	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)
+	/**
+	 * Sort the repository contents by commit time;
+	 * this sorting mode can be combined with
+	 * topological sorting.
+	 */
+	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)
+	/**
+	 * Iterate through the repository contents in reverse
+	 * order; this sorting mode can be combined with
+	 * any of the above.
+	 */
+	GIT_SORT_REVERSE = 1 << 2,
+} git_sort_t;
 
 /**
  * Allocate a new revision walker to iterate through a repo.
diff --git a/include/git2/types.h b/include/git2/types.h
index 64cdfcdda..16933976e 100644
--- a/include/git2/types.h
+++ b/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;