Merge pull request #5806 from punkymaniac/comment-format Fix documentation formating on repository.h
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193
diff --git a/include/git2/repository.h b/include/git2/repository.h
index 9ddcd34..45becc7 100644
--- a/include/git2/repository.h
+++ b/include/git2/repository.h
@@ -219,36 +219,54 @@ GIT_EXTERN(int) git_repository_init(
*
* These flags configure extra behaviors to `git_repository_init_ext`.
* In every case, the default behavior is the zero value (i.e. flag is
- * not set). Just OR the flag values together for the `flags` parameter
- * when initializing a new repo. Details of individual values are:
- *
- * * BARE - Create a bare repository with no working directory.
- * * NO_REINIT - Return an GIT_EEXISTS error if the repo_path appears to
- * already be an git repository.
- * * NO_DOTGIT_DIR - Normally a "/.git/" will be appended to the repo
- * path for non-bare repos (if it is not already there), but
- * passing this flag prevents that behavior.
- * * MKDIR - Make the repo_path (and workdir_path) as needed. Init is
- * always willing to create the ".git" directory even without this
- * flag. This flag tells init to create the trailing component of
- * the repo and workdir paths as needed.
- * * MKPATH - Recursively make all components of the repo and workdir
- * paths as necessary.
- * * EXTERNAL_TEMPLATE - libgit2 normally uses internal templates to
- * initialize a new repo. This flags enables external templates,
- * looking the "template_path" from the options if set, or the
- * `init.templatedir` global config if not, or falling back on
- * "/usr/share/git-core/templates" if it exists.
- * * GIT_REPOSITORY_INIT_RELATIVE_GITLINK - If an alternate workdir is
- * specified, use relative paths for the gitdir and core.worktree.
+ * not set). Just OR the flag values together for the `flags` parameter
+ * when initializing a new repo.
*/
typedef enum {
+ /**
+ * Create a bare repository with no working directory.
+ */
GIT_REPOSITORY_INIT_BARE = (1u << 0),
+
+ /**
+ * Return an GIT_EEXISTS error if the repo_path appears to already be
+ * an git repository.
+ */
GIT_REPOSITORY_INIT_NO_REINIT = (1u << 1),
+
+ /**
+ * Normally a "/.git/" will be appended to the repo path for
+ * non-bare repos (if it is not already there), but passing this flag
+ * prevents that behavior.
+ */
GIT_REPOSITORY_INIT_NO_DOTGIT_DIR = (1u << 2),
+
+ /**
+ * Make the repo_path (and workdir_path) as needed. Init is always willing
+ * to create the ".git" directory even without this flag. This flag tells
+ * init to create the trailing component of the repo and workdir paths
+ * as needed.
+ */
GIT_REPOSITORY_INIT_MKDIR = (1u << 3),
+
+ /**
+ * Recursively make all components of the repo and workdir paths as
+ * necessary.
+ */
GIT_REPOSITORY_INIT_MKPATH = (1u << 4),
+
+ /**
+ * libgit2 normally uses internal templates to initialize a new repo.
+ * This flags enables external templates, looking the "template_path" from
+ * the options if set, or the `init.templatedir` global config if not,
+ * or falling back on "/usr/share/git-core/templates" if it exists.
+ */
GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE = (1u << 5),
+
+ /**
+ * If an alternate workdir is specified, use relative paths for the gitdir
+ * and core.worktree.
+ */
GIT_REPOSITORY_INIT_RELATIVE_GITLINK = (1u << 6),
} git_repository_init_flag_t;
@@ -257,17 +275,23 @@ typedef enum {
*
* Set the mode field of the `git_repository_init_options` structure
* either to the custom mode that you would like, or to one of the
- * following modes:
- *
- * * SHARED_UMASK - Use permissions configured by umask - the default.
- * * SHARED_GROUP - Use "--shared=group" behavior, chmod'ing the new repo
- * to be group writable and "g+sx" for sticky group assignment.
- * * SHARED_ALL - Use "--shared=all" behavior, adding world readability.
- * * Anything else - Set to custom value.
+ * defined modes.
*/
typedef enum {
+ /**
+ * Use permissions configured by umask - the default.
+ */
GIT_REPOSITORY_INIT_SHARED_UMASK = 0,
+
+ /**
+ * Use "--shared=group" behavior, chmod'ing the new repo to be group
+ * writable and "g+sx" for sticky group assignment.
+ */
GIT_REPOSITORY_INIT_SHARED_GROUP = 0002775,
+
+ /**
+ * Use "--shared=all" behavior, adding world readability.
+ */
GIT_REPOSITORY_INIT_SHARED_ALL = 0002777,
} git_repository_init_mode_t;
@@ -275,38 +299,57 @@ typedef enum {
* Extended options structure for `git_repository_init_ext`.
*
* This contains extra options for `git_repository_init_ext` that enable
- * additional initialization features. The fields are:
- *
- * * flags - Combination of GIT_REPOSITORY_INIT flags above.
- * * mode - Set to one of the standard GIT_REPOSITORY_INIT_SHARED_...
- * constants above, or to a custom value that you would like.
- * * workdir_path - The path to the working dir or NULL for default (i.e.
- * repo_path parent on non-bare repos). IF THIS IS RELATIVE PATH,
- * IT WILL BE EVALUATED RELATIVE TO THE REPO_PATH. If this is not
- * the "natural" working directory, a .git gitlink file will be
- * created here linking to the repo_path.
- * * description - If set, this will be used to initialize the "description"
- * file in the repository, instead of using the template content.
- * * template_path - When GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE is set,
- * this contains the path to use for the template directory. If
- * this is NULL, the config or default directory options will be
- * used instead.
- * * initial_head - The name of the head to point HEAD at. If NULL, then
- * this will be treated as "master" and the HEAD ref will be set
- * to "refs/heads/master". If this begins with "refs/" it will be
- * used verbatim; otherwise "refs/heads/" will be prefixed.
- * * origin_url - If this is non-NULL, then after the rest of the
- * repository initialization is completed, an "origin" remote
- * will be added pointing to this URL.
+ * additional initialization features.
*/
typedef struct {
unsigned int version;
+
+ /**
+ * Combination of GIT_REPOSITORY_INIT flags above.
+ */
uint32_t flags;
+
+ /**
+ * Set to one of the standard GIT_REPOSITORY_INIT_SHARED_... constants
+ * above, or to a custom value that you would like.
+ */
uint32_t mode;
+
+ /**
+ * The path to the working dir or NULL for default (i.e. repo_path parent
+ * on non-bare repos). IF THIS IS RELATIVE PATH, IT WILL BE EVALUATED
+ * RELATIVE TO THE REPO_PATH. If this is not the "natural" working
+ * directory, a .git gitlink file will be created here linking to the
+ * repo_path.
+ */
const char *workdir_path;
+
+ /**
+ * If set, this will be used to initialize the "description" file in the
+ * repository, instead of using the template content.
+ */
const char *description;
+
+ /**
+ * When GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE is set, this contains
+ * the path to use for the template directory. If this is NULL, the config
+ * or default directory options will be used instead.
+ */
const char *template_path;
+
+ /**
+ * The name of the head to point HEAD at. If NULL, then this will be
+ * treated as "master" and the HEAD ref will be set to "refs/heads/master".
+ * If this begins with "refs/" it will be used verbatim;
+ * otherwise "refs/heads/" will be prefixed.
+ */
const char *initial_head;
+
+ /**
+ * If this is non-NULL, then after the rest of the repository
+ * initialization is completed, an "origin" remote will be added
+ * pointing to this URL.
+ */
const char *origin_url;
} git_repository_init_options;