Format comments for use with docco

Author: ben

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

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