8000 Merge pull request #6168 from punkymaniac/patch-documentation-2 · libgit2/libgit2@258df9c · GitHub
[go: up one dir, main page]
Skip to content

Commit 258df9c

Browse files
ethomsonethomson
authored
Merge pull request #6168 from punkymaniac/patch-documentation-2
Improve documentation
2 parents d298059 + d4232e7 commit 258df9c

32 files changed

+144
-9
lines changed

‎include/git2/apply.h

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@ GIT_BEGIN_DECL
3232
*
3333
* @param delta The delta to be applied
3434
* @param payload User-specified payload
35+
* @return 0 if the delta is applied, < 0 if the apply process will be aborted
36+
* or > 0 if the delta will not be applied.
3537
*/
3638
typedef int GIT_CALLBACK(git_apply_delta_cb)(
3739
const git_diff_delta *delta,
@@ -48,6 +50,8 @@ typedef int GIT_CALLBACK(git_apply_delta_cb)(
4850
*
4951
* @param hunk The hunk to be applied
5052
* @param payload User-specified payload
53+
* @return 0 if the hunk is applied, < 0 if the apply process will be aborted
54+
* or > 0 if the hunk will not be applied.
5155
*/
5256
typedef int GIT_CALLBACK(git_apply_hunk_cb)(
5357
const git_diff_hunk *hunk,
@@ -89,6 +93,16 @@ typedef struct {
8993
#define GIT_APPLY_OPTIONS_VERSION 1
9094
#define GIT_APPLY_OPTIONS_INIT {GIT_APPLY_OPTIONS_VERSION}
9195

96+
/**
97+
* Initialize git_apply_options structure
98+
*
99+
* Initialize a `git_apply_options` with default values. Equivalent to creating
100+
* an instance with GIT_APPLY_OPTIONS_INIT.
101+
*
102+
* @param opts The `git_apply_options` struct to initialize.
103+
* @param version The struct version; pass `GIT_APPLY_OPTIONS_VERSION`
104+
* @return 0 on success or -1 on failure.
105+
*/
92106
GIT_EXTERN(int) 9E88 git_apply_options_init(git_apply_options *opts, unsigned int version);
93107

94108
/**

‎include/git2/attr.h

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -177,6 +177,7 @@ typedef struct {
177177
* not have to exist, but if it does not, then it will be
178178
* treated as a plain file (not a directory).
179179
* @param name The name of the attribute to look up.
180+
* @return 0 or an error code.
180181
*/
181182
GIT_EXTERN(int) git_attr_get(
182183
const char **value_out,
@@ -199,6 +200,7 @@ GIT_EXTERN(int) git_attr_get(
199200
* not have to exist, but if it does not, then it will be
200201
* treated as a plain file (not a directory).
201202
* @param name The name of the attribute to look up.
203+
* @return 0 or an error code.
202204
*/
203205
GIT_EXTERN(int) git_attr_get_ext(
204206
const char **value_out,
@@ -235,6 +237,7 @@ GIT_EXTERN(int) git_attr_get_ext(
235237
* it will be treated as a plain file (i.e. not a directory).
236238
* @param num_attr The number of attributes being looked up
237239
* @param names An array of num_attr strings containing attribute names.
240+
* @return 0 or an error code.
238241
*/
239242
GIT_EXTERN(int) git_attr_get_many(
240243
const char **values_out,
@@ -259,6 +262,7 @@ GIT_EXTERN(int) git_attr_get_many(
259262
* it will be treated as a plain file (i.e. not a directory).
260263
* @param num_attr The number of attributes being looked up
261264
* @param names An array of num_attr strings containing attribute names.
265+
* @return 0 or an error code.
262266
*/
263267
GIT_EXTERN(int) git_attr_get_many_ext(
264268
const char **values_out,
@@ -349,6 +353,11 @@ GIT_EXTERN(int) git_attr_cache_flush(
349353
* macro, you would call:
350354
*
351355
* git_attr_add_macro(repo, "binary", "-diff -crlf");
356+
*
357+
* @param repo The repository to add the macro in.
358+
* @param name The name of the macro.
359+
* @param values The value for the macro.
360+
* @return 0 or an error code.
352361
*/
353362
GIT_EXTERN(int) git_attr_add_macro(
354363
git_repository *repo,

‎include/git2/blame.h

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -203,6 +203,9 @@ typedef struct git_blame git_blame;
203203

204204
/**
205205
* Gets the number of hunks that exist in the blame structure.
206+
*
207+
* @param blame The blame structure to query.
208+
* @return The number of hunks.
206209
*/
207210
GIT_EXTERN(uint32_t) git_blame_get_hunk_count(git_blame *blame);
208211

‎include/git2/blob.h

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -302,6 +302,7 @@ GIT_EXTERN(int) git_blob_data_is_binary(const char *data, size_t len);
302302
*
303303
* @param out Pointer to store the copy of the object
304304
* @param source Original object to copy
305+
* @return 0.
305306
*/
306307
GIT_EXTERN(int) git_blob_dup(git_blob **out, git_blob *source);
307308

‎include/git2/branch.h

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,8 @@ GIT_BEGIN_DECL
3434
*
3535
* @param out Pointer where to store the underlying reference.
3636
*
37+
* @param repo the repository to create the branch in.
38+
*
3739
* @param branch_name Name for the branch; this name is
3840
* validated for consistency. It should also not conflict with
3941
* an already existing branch name.

‎include/git2/commit.h

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -479,6 +479,7 @@ GIT_EXTERN(int) git_commit_create_buffer(
479479
* to the commit and write it into the given repository.
480480
*
481481
* @param out the resulting commit id
482+
* @param repo the repository to create the commit in.
482483
* @param commit_content the content of the unsigned commit object
483484
* @param signature the signature to add to the commit. Leave `NULL`
484485
* to create a commit without adding a signature field.
@@ -499,6 +500,7 @@ GIT_EXTERN(int) git_commit_create_with_signature(
499500
*
500501
* @param out Pointer to store the copy of the commit
501502
* @param source Original commit to copy
503+
* @return 0
502504
*/
503505
GIT_EXTERN(int) git_commit_dup(git_commit **out, git_commit *source);
504506

‎include/git2/common.h

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -167,6 +167,9 @@ typedef enum {
167167
* - GIT_FEATURE_SSH
168168
* Libgit2 supports the SSH protocol for network operations. This requires
169169
* the libssh2 library to be found when compiling libgit2
170+
*
171+
* - GIT_FEATURE_NSEC
172+
* Libgit2 supports the sub-second resolution in file modification times.
170173
*/
171174
GIT_EXTERN(int) git_libgit2_features(void);
172175

‎include/git2/config.h

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -72,14 +72,17 @@ typedef struct git_config_entry {
7272

7373
/**
7474
* Free a config entry
75+
*
76+
* @param entry The entry to free.
7577
*/
76-
GIT_EXTERN(void) git_config_entry_free(git_config_entry *);
78+
GIT_EXTERN(void) git_config_entry_free(git_config_entry *entry);
7779

7880
/**
7981
* A config enumeration callback
8082
*
8183
* @param entry the entry currently being enumerated
8284
* @param payload a user-specified pointer
85+
* @return non-zero to terminate the iteration.
8386
*/
8487
typedef int GIT_CALLBACK(git_config_foreach_cb)(const git_config_entry *entry, void *payload);
8588

@@ -269,6 +272,7 @@ GIT_EXTERN(int) git_config_open_level(
269272
*
270273
* @param out pointer in which to store the config object
271274
* @param config the config object in which to look
275+
* @return 0 or an error code.
272276
*/
273277
GIT_EXTERN(int) git_config_open_global(git_config **out, git_config *config);
274278

@@ -422,6 +426,7 @@ GIT_EXTERN(int) git_config_get_string_buf(git_buf *out, const git_config *cfg, c
422426
* interested in. Use NULL to indicate all
423427
* @param callb 1241 ack the function to be called on each value of the variable
424428
* @param payload opaque pointer to pass to the callback
429+
* @return 0 or an error code.
425430
*/
426431
GIT_EXTERN(int) git_config_get_multivar_foreach(const git_config *cfg, const char *name, const char *regexp, git_config_foreach_cb callback, void *payload);
427432

@@ -437,6 +442,7 @@ GIT_EXTERN(int) git_config_get_multivar_foreach(const git_config *cfg, const cha
437442
* @param name the variable's name
438443
* @param regexp regular expression to filter which variables we're
439444
* interested in. Use NULL to indicate all
445+
* @return 0 or an error code.
440446
*/
441447
GIT_EXTERN(int) git_config_multivar_iterator_new(git_config_iterator **out, const git_config *cfg, const char *name, const char *regexp);
442448

@@ -515,6 +521,7 @@ GIT_EXTERN(int) git_config_set_string(git_config *cfg, const char *name, const c
515521
* @param name the variable's name
516522
* @param regexp a regular expression to indicate which values to replace
517523
* @param value the new value.
524+
* @return 0 or an error code.
518525
*/
519526
GIT_EXTERN(int) git_config_set_multivar(git_config *cfg, const char *name, const char *regexp, const char *value);
520527

@@ -524,6 +531,7 @@ GIT_EXTERN(int) git_config_set_multivar(git_config *cfg, const char *name, const
524531
*
525532
* @param cfg the configuration
526533
* @param name the variable to delete
534+
* @return 0 or an error code.
527535
*/
528536
GIT_EXTERN(int) git_config_delete_entry(git_config *cfg, const char *name);
529537

@@ -568,7 +576,8 @@ GIT_EXTERN(int) git_config_foreach(
568576
* `git_config_iterator_free` when done.
569577
*
570578
* @param out pointer to store the iterator
571-
* @param cfg where to ge the variables from
579+
* @param cfg where to get the variables from
580+
* @return 0 or an error code.
572581
*/
573582
GIT_EXTERN(int) git_config_iterator_new(git_config_iterator **out, const git_config *cfg);
574583

@@ -585,6 +594,7 @@ GIT_EXTERN(int) git_config_iterator_new(git_config_iterator **out, const git_con
585594
* @param out pointer to store the iterator
586595
* @param cfg where to ge the variables from
587596
* @param regexp regular expression to match the names
597+
* @return 0 or an error code.
588598
*/
589599
GIT_EXTERN(int) git_config_iterator_glob_new(git_config_iterator **out, const git_config *cfg, const char *regexp);
590600

@@ -662,6 +672,7 @@ GIT_EXTERN(int) git_config_get_mapped(
662672
* @param maps array of `git_configmap` objects specifying the possible mappings
663673
* @param map_n number of mapping objects in `maps`
664674
* @param value value to parse
675+
* @return 0 or an error code.
665676
*/
666677
GIT_EXTERN(int) git_config_lookup_map_value(
667678
int *out,
@@ -678,6 +689,7 @@ GIT_EXTERN(int) git_config_lookup_map_value(
678689
*
679690
* @param out place to store the result of the parsing
680691
* @param value value to parse
692+
* @return 0 or an error code.
681693
*/
682694
GIT_EXTERN(int) git_config_parse_bool(int *out, const char *value);
683695

@@ -690,6 +702,7 @@ GIT_EXTERN(int) git_config_parse_bool(int *out, const char *value);
690702
*
691703
* @param out place to store the result of the parsing
692704
* @param value value to parse
705+
* @return 0 or an error code.
693706
*/
694707
GIT_EXTERN(int) git_config_parse_int32(int32_t *out, const char *value);
695708

@@ -702,6 +715,7 @@ GIT_EXTERN(int) git_config_parse_int32(int32_t *out, const char *value);
702715
*
703716
* @param out place to store the result of the parsing
704717
* @param value value to parse
718+
* @return 0 or an error code.
705719
*/
706720
GIT_EXTERN(int) git_config_parse_int64(int64_t *out, const char *value);
707721

@@ -717,6 +731,7 @@ GIT_EXTERN(int) git_config_parse_int64(int64_t *out, const char *value);
717731
*
718732
* @param out placae to store the result of parsing
719733
* @param value the path to evaluate
734+
* @return 0 or an error code.
720735
*/
721736
GIT_EXTERN(int) git_config_parse_path(git_buf *out, const char *value);
722737

@@ -735,6 +750,7 @@ GIT_EXTERN(int) git_config_parse_path(git_buf *out, const char *value);
735750
* @param regexp regular expression to match against config names (can be NULL)
736751
* @param callback the function to call on each variable
737752
* @param payload the data to pass to the callback
753+
* @return 0 or an error code.
738754
*/
739755
GIT_EXTERN(int) git_config_backend_foreach_match(
740756
git_config_backend *backend,

‎include/git2/credential.h

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -254,6 +254,7 @@ typedef void GIT_CALLBACK(git_credential_ssh_interactive_cb)(
254254
* Create a new ssh keyboard-interactive based credential object.
255255
* The supplied credential parameter will be internally duplicated.
256256
*
257+
* @param out The newly created credential object.
257258
* @param username Username to use to authenticate.
258259
* @param prompt_callback The callback method used for prompts.
259260
* @param payload Additional data to pass to the callback.

‎include/git2/credential_helpers.h

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ typedef struct git_credential_userpass_payload {
3939
* @param allowed_types A bitmask stating which credential types are OK to return.
4040
* @param payload The payload provided when specifying this callback. (This is
4141
* interpreted as a `git_credential_userpass_payload*`.)
42+
* @return 0 or an error code.
4243
*/
4344
GIT_EXTERN(int) git_credential_userpass(
4445
git_credential **out,

‎include/git2/describe.h

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -142,6 +142,7 @@ typedef struct git_describe_result git_describe_result;
142142
* you're done with it.
143143
* @param committish a committish to describe
144144
* @param opts the lookup options (or NULL for defaults)
145+
* @return 0 or an error code.
145146
*/
146147
GIT_EXTERN(int) git_describe_commit(
147148
git_describe_result **result,
@@ -159,6 +160,7 @@ GIT_EXTERN(int) git_describe_commit(
159160
* you're done with it.
160161
* @param repo the repository in which to perform the describe
161162
* @param opts the lookup options (or NULL for defaults)
163+
* @return 0 or an error code.
162164
*/
163165
GIT_EXTERN(int) git_describe_workdir(
164166
git_describe_result **out,
@@ -172,6 +174,7 @@ GIT_EXTERN(int) git_describe_workdir(
172174
* @param result the result from `git_describe_commit()` or
173175
* `git_describe_workdir()`.
174176
* @param opts the formatting options (or NULL for defaults)
177+
* @return 0 or an error code.
175178
*/
176179
GIT_EXTERN(int) git_describe_format(
177180
git_buf *out,
@@ -180,6 +183,8 @@ GIT_EXTERN(int) git_describe_format(
180183

181184
/**
182185
* Free the describe result.
186+
*
187+
* @param result The result to free.
183188
*/
184189
GIT_EXTERN(void) git_describe_result_free(git_describe_result *result);
185190

‎include/git2/diff.h

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -831,6 +831,7 @@ GIT_EXTERN(void) git_diff_free(git_diff *diff);
831831
* @param old_tree A git_tree object to diff from, or NULL for empty tree.
832832
* @param new_tree A git_tree object to diff to, or NULL for empty tree.
833833
* @param opts Structure with options to influence diff or NULL for defaults.
834+
* @return 0 or an error code.
834835
*/
835836
GIT_EXTERN(int) git_diff_tree_to_tree(
836837
git_diff **diff,
@@ -857,6 +858,7 @@ GIT_EXTERN(int) git_diff_tree_to_tree(
857858
* @param old_tree A git_tree object to diff from, or NULL for empty tree.
858859
* @param index The index to diff with; repo index used if NULL.
859860
* @param opts Structure with options to influence diff or NULL for defaults.
861+
* @return 0 or an error code.
860862
*/
861863
GIT_EXTERN(int) git_diff_tree_to_index(
862864
git_diff **diff,
@@ -884,6 +886,7 @@ GIT_EXTERN(int) git_diff_tree_to_index(
884886
* @param repo The repository.
885887
* @param index The index to diff from; repo index used if NULL.
886888
* @param opts Structure with options to influence diff or NULL for defaults.
889+
* @return 0 or an error code.
887890
*/
888891
GIT_EXTERN(int) git_diff_index_to_workdir(
889892
git_diff **diff,
@@ -913,6 +916,7 @@ GIT_EXTERN(int) git_diff_index_to_workdir(
913916
* @param repo The repository containing the tree.
914917
* @param old_tree A git_tree object to diff from, or NULL for empty tree.
915918
* @param opts Structure with options to influence diff or NULL for defaults.
919+
* @return 0 or an error code.
916920
*/
917921
GIT_EXTERN(int) git_diff_tree_to_workdir(
918922
git_diff **diff,
@@ -932,6 +936,7 @@ GIT_EXTERN(int) git_diff_tree_to_workdir(
932936
* @param repo The repository containing the tree.
933937
* @param old_tree A git_tree object to diff from, or NULL for empty tree.
934938
* @param opts Structure with options to influence diff or NULL for defaults.
939+
* @return 0 or an error code.
935940
*/
936941
GIT_EXTERN(int) git_diff_tree_to_workdir_with_index(
937942
git_diff **diff,
@@ -950,6 +955,7 @@ GIT_EXTERN(int) git_diff_tree_to_workdir_with_index(
950955
* @param old_index A git_index object to diff from.
951956
* @param new_index A git_index object to diff to.
952957
* @param opts Structure with options to influence diff or NULL for defaults.
958+
* @return 0 or an error code.
953959
*/
954960
GIT_EXTERN(int) git_diff_index_to_index(
955961
git_diff **diff,
@@ -970,6 +976,7 @@ GIT_EXTERN(int) git_diff_index_to_index(
970976
*
971977
* @param onto Diff to merge into.
972978
* @param from Diff to merge.
979+
* @return 0 or an error code.
973980
*/
974981
GIT_EXTERN(int) git_diff_merge(
975982
git_diff *onto,

0 commit comments

Comments
 (0)
0