Format comments for use with docco

5 files changed, 86 insertions, 72 deletions

diff --git a/examples/diff.c b/examples/diff.c
index d39979117..381325839 100644
--- a/examples/diff.c
+++ b/examples/diff.c
@@ -7,7 +7,7 @@
 
 #include "common.h"
 
-/*
+/**
  * This example demonstrates the use of the libgit2 diff APIs to
  * create `git_diff` objects and display them, emulating a number of
  * core Git `diff` command line options.
@@ -26,11 +26,7 @@ static const char *colors[] = {
 	"\033[36m" /* cyan */
 };
 
-/* this implements very rudimentary colorized output */
-static int color_printer(
-	const git_diff_delta*, const git_diff_hunk*, const git_diff_line*, void*);
-
-/* the 'opts' struct captures all the various parsed command line options */
+/** The 'opts' struct captures all the various parsed command line options. */
 struct opts {
 	git_diff_options diffopts;
 	git_diff_find_options findopts;
@@ -43,6 +39,8 @@ struct opts {
 };
 
 static void parse_opts(struct opts *o, int argc, char *argv[]);
+static int color_printer(
+	const git_diff_delta*, const git_diff_hunk*, const git_diff_line*, void*);
 
 int main(int argc, char *argv[])
 {
@@ -61,12 +59,14 @@ int main(int argc, char *argv[])
 	check_lg2(git_repository_open_ext(&repo, o.dir, 0, NULL),
 		"Could not open repository", o.dir);
 
-	/* Possible argument patterns:
-	 *   <sha1> <sha2>
-	 *   <sha1> --cached
-	 *   <sha1>
-	 *   --cached
-	 *   nothing
+	/**
+	 * Possible argument patterns:
+	 *
+	 *  * <sha1> <sha2>
+	 *  * <sha1> --cached
+	 *  * <sha1>
+	 *  * --cached
+	 *  * nothing
 	 *
 	 * Currently ranged arguments like <sha1>..<sha2> and <sha1>...<sha2>
 	 * are not supported in this example
@@ -100,14 +100,14 @@ int main(int argc, char *argv[])
 			git_diff_index_to_workdir(&diff, repo, NULL, &o.diffopts),
 			"diff index to working directory", NULL);
 
-	/* apply rename and copy detection if requested */
+	/** Apply rename and copy detection if requested. */
 
 	if ((o.findopts.flags & GIT_DIFF_FIND_ALL) != 0)
 		check_lg2(
 			git_diff_find_similar(diff, &o.findopts),
 			"finding renames and copies", NULL);
 
-	/* generate simple output using libgit2 display helper */
+	/** Generate simple output using libgit2 display helper. */
 
 	if (o.color >= 0)
 		fputs(colors[0], stdout);
@@ -119,7 +119,7 @@ int main(int argc, char *argv[])
 	if (o.color >= 0)
 		fputs(colors[0], stdout);
 
-	/* cleanup before exiting */
+	/** Cleanup before exiting. */
 
 	git_diff_free(diff);
 	git_tree_free(t1);
@@ -141,6 +141,7 @@ static void usage(const char *message, const char *arg)
 	exit(1);
 }
 
+/** This implements very rudimentary colorized output. */
 static int color_printer(
 	const git_diff_delta *delta,
 	const git_diff_hunk *hunk,
@@ -177,7 +178,7 @@ static void parse_opts(struct opts *o, int argc, char *argv[])
 {
 	struct args_info args = ARGS_INFO_INIT;
 
-	/* parse arguments as copied from git-diff */
+	/* Parse arguments as copied from git-diff. */
 
 	for (args.pos = 1; args.pos < argc; ++args.pos) {
 		const char *a = argv[args.pos];
diff --git a/examples/init.c b/examples/init.c
index 5bec17b9d..1c371252e 100644
--- a/examples/init.c
+++ b/examples/init.c
@@ -1,4 +1,13 @@
 /*
+ * Copyright (C) the libgit2 contributors. All rights reserved.
+ *
+ * This file is part of libgit2, distributed under the GNU GPL v2 with
+ * a Linking Exception. For full terms see the included COPYING file.
+ */
+
+#include "common.h"
+
+/**
  * This is a sample program that is similar to "git init".  See the
  * documentation for that (try "git help init") to understand what this
  * program is emulating.
@@ -8,16 +17,9 @@
  * This also contains a special additional option that regular "git init"
  * does not support which is "--initial-commit" to make a first empty commit.
  * That is demonstrated in the "create_initial_commit" helper function.
- *
- * Copyright (C) the libgit2 contributors. All rights reserved.
- *
- * This file is part of libgit2, distributed under the GNU GPL v2 with
- * a Linking Exception. For full terms see the included COPYING file.
  */
 
-#include "common.h"
-
-/* forward declarations of helpers */
+/** Forward declarations of helpers */
 struct opts {
 	int no_options;
 	int quiet;
@@ -41,17 +43,19 @@ int main(int argc, char *argv[])
 
 	parse_opts(&o, argc, argv);
 
-	/* Initialize repository */
+	/* Initialize repository. */
 
 	if (o.no_options) {
-		/* No options were specified, so let's demonstrate the default
+		/**
+		 * No options were specified, so let's demonstrate the default
 		 * simple case of git_repository_init() API usage...
 		 */
 		check_lg2(git_repository_init(&repo, o.dir, 0),
 			"Could not initialize repository", NULL);
 	}
 	else {
-		/* Some command line options were specified, so we'll use the
+		/**
+		 * Some command line options were specified, so we'll use the
 		 * extended init API to handle them
 		 */
 		git_repository_init_options initopts = GIT_REPOSITORY_INIT_OPTIONS_INIT;
@@ -66,7 +70,8 @@ int main(int argc, char *argv[])
 		}
 
 		if (o.gitdir) {
-			/* if you specified a separate git directory, then initialize
+			/**
+			 * If you specified a separate git directory, then initialize
 			 * the repository at that path and use the second path as the
 			 * working directory of the repository (with a git-link file)
 			 */
@@ -81,7 +86,7 @@ int main(int argc, char *argv[])
 				"Could not initialize repository", NULL);
 	}
 
-	/* Print a message to stdout like "git init" does */
+	/** Print a message to stdout like "git init" does. */
 
 	if (!o.quiet) {
 		if (o.bare || o.gitdir)
@@ -92,7 +97,8 @@ int main(int argc, char *argv[])
 		printf("Initialized empty Git repository in %s\n", o.dir);
 	}
 
-	/* As an extension to the basic "git init" command, this example
+	/**
+	 * As an extension to the basic "git init" command, this example
 	 * gives the option to create an empty initial commit.  This is
 	 * mostly to demonstrate what it takes to do that, but also some
 	 * people like to have that empty base commit in their repo.
@@ -108,7 +114,8 @@ int main(int argc, char *argv[])
 	return 0;
 }
 
-/* Unlike regular "git init", this example shows how to create an initial
+/**
+ * Unlike regular "git init", this example shows how to create an initial
  * empty commit in the repository.  This is the helper function that does
  * that.
  */
@@ -119,7 +126,7 @@ static void create_initial_commit(git_repository *repo)
 	git_oid tree_id, commit_id;
 	git_tree *tree;
 
-	/* First use the config to initialize a commit signature for the user */
+	/** First use the config to initialize a commit signature for the user. */
 
 	if (git_signature_default(&sig, repo) < 0)
 		fatal("Unable to create a commit signature.",
@@ -130,7 +137,8 @@ static void create_initial_commit(git_repository *repo)
 	if (git_repository_index(&index, repo) < 0)
 		fatal("Could not open repository index", NULL);
 
-	/* Outside of this example, you could call git_index_add_bypath()
+	/**
+	 * Outside of this example, you could call git_index_add_bypath()
 	 * here to put actual files into the index.  For our purposes, we'll
 	 * leave it empty for now.
 	 */
@@ -143,7 +151,8 @@ static void create_initial_commit(git_repository *repo)
 	if (git_tree_lookup(&tree, repo, &tree_id) < 0)
 		fatal("Could not look up initial tree", NULL);
 
-	/* Ready to create the initial commit
+	/**
+	 * Ready to create the initial commit.
 	 *
 	 * Normally creating a commit would involve looking up the current
 	 * HEAD commit and making that be the parent of the initial commit,
@@ -155,7 +164,7 @@ static void create_initial_commit(git_repository *repo)
 			NULL, "Initial commit", tree, 0) < 0)
 		fatal("Could not create the initial commit", NULL);
 
-	/* Clean up so we don't leak memory */
+	/** Clean up so we don't leak memory. */
 
 	git_tree_free(tree);
 	git_signature_free(sig);
@@ -171,7 +180,7 @@ static void usage(const char *error, const char *arg)
 	exit(1);
 }
 
-/* parse the tail of the --shared= argument */
+/** Parse the tail of the --shared= argument. */
 static uint32_t parse_shared(const char *shared)
 {
 	if (!strcmp(shared, "false") || !strcmp(shared, "umask"))
@@ -204,7 +213,7 @@ static void parse_opts(struct opts *o, int argc, char *argv[])
 	struct args_info args = ARGS_INFO_INIT;
 	const char *sharedarg;
 
-	/* Process arguments */
+	/** Process arguments. */
 
 	for (args.pos = 1; args.pos < argc; ++args.pos) {
 		char *a = argv[args.pos];
diff --git a/examples/log.c b/examples/log.c
index 270de7c5d..4a0487a42 100644
--- a/examples/log.c
+++ b/examples/log.c
@@ -7,23 +7,25 @@
 
 #include "common.h"
 
-/*
+/**
  * This example demonstrates the libgit2 rev walker APIs to roughly
  * simulate the output of `git log` and a few of command line arguments.
  * `git log` has many many options and this only shows a few of them.
  *
  * This does not have:
+ *
  * - Robust error handling
  * - Colorized or paginated output formatting
  * - Most of the `git log` options
  *
  * This does have:
+ *
  * - Examples of translating command line arguments to equivalent libgit2
  *   revwalker configuration calls
  * - Simplified options to apply pathspec limits and to show basic diffs
  */
 
-/* log_state represents walker being configured while handling options */
+/** log_state represents walker being configured while handling options */
 struct log_state {
 	git_repository *repo;
 	const char *repodir;
@@ -33,12 +35,12 @@ struct log_state {
 	int revisions;
 };
 
-/* utility functions that are called to configure the walker */
+/** utility functions that are called to configure the walker */
 static void set_sorting(struct log_state *s, unsigned int sort_mode);
 static void push_rev(struct log_state *s, git_object *obj, int hide);
 static int add_revision(struct log_state *s, const char *revstr);
 
-/* log_options holds other command line options that affect log output */
+/** log_options holds other command line options that affect log output */
 struct log_options {
 	int show_diff;
 	int skip, limit;
@@ -49,7 +51,7 @@ struct log_options {
 	char *committer;
 };
 
-/* utility functions that parse options and help with log output */
+/** utility functions that parse options and help with log output */
 static int parse_options(
 	struct log_state *s, struct log_options *opt, int argc, char **argv);
 static void print_time(const git_time *intime, const char *prefix);
@@ -69,7 +71,7 @@ int main(int argc, char *argv[])
 
 	git_threads_init();
 
-	/* parse arguments and set up revwalker */
+	/** Parse arguments and set up revwalker. */
 
 	last_arg = parse_options(&s, &opt, argc, argv);
 
@@ -82,7 +84,7 @@ int main(int argc, char *argv[])
 	if (!s.revisions)
 		add_revision(&s, NULL);
 
-	/* use the revwalker to traverse the history */
+	/** Use the revwalker to traverse the history. */
 
 	printed = count = 0;
 
@@ -163,12 +165,12 @@ int main(int argc, char *argv[])
 	return 0;
 }
 
-/* push object (for hide or show) onto revwalker */
+/** Push object (for hide or show) onto revwalker. */
 static void push_rev(struct log_state *s, git_object *obj, int hide)
 {
 	hide = s->hide ^ hide;
 
-	/* create revwalker on demand if it doesn't already exist */
+	/** Create revwalker on demand if it doesn't already exist. */
 	if (!s->walker) {
 		check_lg2(git_revwalk_new(&s->walker, s->repo),
 			"Could not create revision walker", NULL);
@@ -188,13 +190,13 @@ static void push_rev(struct log_state *s, git_object *obj, int hide)
 	git_object_free(obj);
 }
 
-/* parse revision string and add revs to walker */
+/** Parse revision string and add revs to walker. */
 static int add_revision(struct log_state *s, const char *revstr)
 {
 	git_revspec revs;
 	int hide = 0;
 
-	/* open repo on demand if it isn't already open */
+	/** Open repo on demand if it isn't already open. */
 	if (!s->repo) {
 		if (!s->repodir) s->repodir = ".";
 		check_lg2(git_repository_open_ext(&s->repo, s->repodir, 0, NULL),
@@ -238,17 +240,17 @@ static int add_revision(struct log_state *s, const char *revstr)
 	return 0;
 }
 
-/* update revwalker with sorting mode */
+/** Update revwalker with sorting mode. */
 static void set_sorting(struct log_state *s, unsigned int sort_mode)
 {
-	/* open repo on demand if it isn't already open */
+	/** Open repo on demand if it isn't already open. */
 	if (!s->repo) {
 		if (!s->repodir) s->repodir = ".";
 		check_lg2(git_repository_open_ext(&s->repo, s->repodir, 0, NULL),
 			"Could not open repository", s->repodir);
 	}
 
-	/* create revwalker on demand if it doesn't already exist */
+	/** Create revwalker on demand if it doesn't already exist. */
 	if (!s->walker)
 		check_lg2(git_revwalk_new(&s->walker, s->repo),
 			"Could not create revision walker", NULL);
@@ -261,7 +263,7 @@ static void set_sorting(struct log_state *s, unsigned int sort_mode)
 	git_revwalk_sorting(s->walker, s->sorting);
 }
 
-/* helper to format a git_time value like Git */
+/** Helper to format a git_time value like Git. */
 static void print_time(const git_time *intime, const char *prefix)
 {
 	char sign, out[32];
@@ -288,7 +290,7 @@ static void print_time(const git_time *intime, const char *prefix)
 	printf("%s%s %c%02d%02d\n", prefix, out, sign, hours, minutes);
 }
 
-/* helper to print a commit object */
+/** Helper to print a commit object. */
 static void print_commit(git_commit *commit)
 {
 	char buf[GIT_OID_HEXSZ + 1];
@@ -323,7 +325,7 @@ static void print_commit(git_commit *commit)
 	printf("\n");
 }
 
-/* helper to find how many files in a commit changed from its nth parent */
+/** Helper to find how many files in a commit changed from its nth parent. */
 static int match_with_parent(git_commit *commit, int i, git_diff_options *opts)
 {
 	git_commit *parent;
@@ -349,7 +351,7 @@ static int match_with_parent(git_commit *commit, int i, git_diff_options *opts)
 	return ndeltas > 0;
 }
 
-/* print a usage message for the program */
+/** Print a usage message for the program. */
 static void usage(const char *message, const char *arg)
 {
 	if (message && arg)
@@ -360,7 +362,7 @@ static void usage(const char *message, const char *arg)
 	exit(1);
 }
 
-/* parse some log command line options */
+/** Parse some log command line options. */
 static int parse_options(
 	struct log_state *s, struct log_options *opt, int argc, char **argv)
 {
@@ -379,7 +381,8 @@ static int parse_options(
 		if (a[0] != '-') {
 			if (!add_revision(s, a))
 				s->revisions++;
-			else /* try failed revision parse as filename */
+			else
+				/** Try failed revision parse as filename. */
 				break;
 		} else if (!strcmp(a, "--")) {
 			++args.pos;
@@ -392,15 +395,15 @@ static int parse_options(
 		else if (!strcmp(a, "--reverse"))
 			set_sorting(s, GIT_SORT_REVERSE);
 		else if (match_str_arg(&s->repodir, &args, "--git-dir"))
-			/* found git-dir */;
+			/** Found git-dir. */;
 		else if (match_int_arg(&opt->skip, &args, "--skip", 0))
-			/* found valid --skip */;
+			/** Found valid --skip. */;
 		else if (match_int_arg(&opt->limit, &args, "--max-count", 0))
-			/* found valid --max-count */;
+			/** Found valid --max-count. */;
 		else if (a[1] >= '0' && a[1] <= '9')
 			is_integer(&opt->limit, a + 1, 0);
 		else if (match_int_arg(&opt->limit, &args, "-n", 0))
-			/* found valid -n */;
+			/** Found valid -n. */;
 		else if (!strcmp(a, "--merges"))
 			opt->min_parents = 2;
 		else if (!strcmp(a, "--no-merges"))
@@ -410,9 +413,9 @@ static int parse_options(
 		else if (!strcmp(a, "--no-max-parents"))
 			opt->max_parents = -1;
 		else if (match_int_arg(&opt->max_parents, &args, "--max-parents=", 1))
-			/* found valid --max-parents */;
+			/** Found valid --max-parents. */;
 		else if (match_int_arg(&opt->min_parents, &args, "--min-parents=", 0))
-			/* found valid --min_parents */;
+			/** Found valid --min_parents. */;
 		else if (!strcmp(a, "-p") || !strcmp(a, "-u") || !strcmp(a, "--patch"))
 			opt->show_diff = 1;
 		else
diff --git a/examples/rev-parse.c b/examples/rev-parse.c
index 21f87c881..64a02fe6e 100644
--- a/examples/rev-parse.c
+++ b/examples/rev-parse.c
@@ -7,8 +7,7 @@
 
 #include "common.h"
 
-
-/* Forward declarations for helpers */
+/** Forward declarations for helpers. */
 struct parse_state {
 	git_repository *repo;
 	const char *repodir;
diff --git a/examples/status.c b/examples/status.c
index f6816bcd3..459e6fafb 100644
--- a/examples/status.c
+++ b/examples/status.c
@@ -7,17 +7,19 @@
 
 #include "common.h"
 
-/*
+/**
  * This example demonstrates the use of the libgit2 status APIs,
  * particularly the `git_status_list` object, to roughly simulate the
  * output of running `git status`.  It serves as a simple example of
  * using those APIs to get basic status information.
  *
  * This does not have:
+ *
  * - Robust error handling
  * - Colorized or paginated output formatting
  *
  * This does have:
+ *
  * - Examples of translating command line arguments to the status
  *   options settings to mimic `git status` results.
  * - A sample status formatter that matches the default "long" format
@@ -64,7 +66,7 @@ int main(int argc, char *argv[])
 
 	parse_opts(&o, argc, argv);
 
-	/*
+	/**
 	 * Try to open the repository at the given path (or at the current
 	 * directory if none was given).
 	 */
@@ -75,7 +77,7 @@ int main(int argc, char *argv[])
 		fatal("Cannot report status on bare repository",
 			git_repository_path(repo));
 
-	/*
+	/**
 	 * Run status on the repository
 	 *
 	 * Because we want to simluate a full "git status" run and want to
@@ -140,7 +142,7 @@ static void print_long(git_repository *repo, git_status_list *status)
 
 	(void)repo;
 
-	/* print index changes */
+	/** Print index changes. */
 
 	for (i = 0; i < maxi; ++i) {
 		char *istatus = NULL;
@@ -189,7 +191,7 @@ static void print_long(git_repository *repo, git_status_list *status)
 	}
 	header = 0;
 
-	/* print workdir changes to tracked files */
+	/** Print workdir changes to tracked files. */
 
 	for (i = 0; i < maxi; ++i) {
 		char *wstatus = NULL;
@@ -234,7 +236,7 @@ static void print_long(git_repository *repo, git_status_list *status)
 	}
 	header = 0;
 
-	/* print untracked files */
+	/** Print untracked files. */
 
 	header = 0;
 
@@ -256,7 +258,7 @@ static void print_long(git_repository *repo, git_status_list *status)
 
 	header = 0;
 
-	/* print ignored files */
+	/** Print ignored files. */
 
 	for (i = 0; i < maxi; ++i) {
 		s = git_status_byindex(status, i);