| Message ID | afab6d5f4ed8cbe8e6dcba9a50282a471b542b13.1572343246.git.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Move doc to header files | expand |
On Tue, Oct 29, 2019 at 10:00:45AM +0000, Heba Waly via GitGitGadget wrote: > From: Heba Waly <heba.waly@gmail.com> > > Move the documentation from Documentation/technical/api-revision-walking.txt > to revision.h as it's easier for the developers to find the usage > information beside the code instead of looking for it in another doc file. > > Also documentation/technical/api-revision-walking.txt is removed because the > information it has is now redundant and it'll be hard to keep it up to > date and synchronized with the documentation in the header file. This commit looks nice to me. It also looks like new work for me to update Documentation/MyFirstObjectWalk.txt to reflect this when it's merged later :) Reviewed-by: Emily Shaffer <emilyshaffer@google.com> > > Signed-off-by: Heba Waly <heba.waly@gmail.com> > --- > .../technical/api-revision-walking.txt | 72 ------------------- > revision.h | 59 +++++++++++++++ > 2 files changed, 59 insertions(+), 72 deletions(-) > delete mode 100644 Documentation/technical/api-revision-walking.txt > > diff --git a/Documentation/technical/api-revision-walking.txt b/Documentation/technical/api-revision-walking.txt > deleted file mode 100644 > index 03f9ea6ac4..0000000000 > --- a/Documentation/technical/api-revision-walking.txt > +++ /dev/null > @@ -1,72 +0,0 @@ > -revision walking API > -==================== > - > -The revision walking API offers functions to build a list of revisions > -and then iterate over that list. > - > -Calling sequence > ----------------- > - > -The walking API has a given calling sequence: first you need to > -initialize a rev_info structure, then add revisions to control what kind > -of revision list do you want to get, finally you can iterate over the > -revision list. > - > -Functions > ---------- > - > -`repo_init_revisions`:: > - > - Initialize a rev_info structure with default values. The third > - parameter may be NULL or can be prefix path, and then the `.prefix` > - variable will be set to it. This is typically the first function you > - want to call when you want to deal with a revision list. After calling > - this function, you are free to customize options, like set > - `.ignore_merges` to 0 if you don't want to ignore merges, and so on. See > - `revision.h` for a complete list of available options. > - > -`add_pending_object`:: > - > - This function can be used if you want to add commit objects as revision > - information. You can use the `UNINTERESTING` object flag to indicate if > - you want to include or exclude the given commit (and commits reachable > - from the given commit) from the revision list. > -+ > -NOTE: If you have the commits as a string list then you probably want to > -use setup_revisions(), instead of parsing each string and using this > -function. > - > -`setup_revisions`:: > - > - Parse revision information, filling in the `rev_info` structure, and > - removing the used arguments from the argument list. Returns the number > - of arguments left that weren't recognized, which are also moved to the > - head of the argument list. The last parameter is used in case no > - parameter given by the first two arguments. > - > -`prepare_revision_walk`:: > - > - Prepares the rev_info structure for a walk. You should check if it > - returns any error (non-zero return code) and if it does not, you can > - start using get_revision() to do the iteration. > - > -`get_revision`:: > - > - Takes a pointer to a `rev_info` structure and iterates over it, > - returning a `struct commit *` each time you call it. The end of the > - revision list is indicated by returning a NULL pointer. > - > -`reset_revision_walk`:: > - > - Reset the flags used by the revision walking api. You can use > - this to do multiple sequential revision walks. > - > -Data structures > ---------------- > - > -Talk about <revision.h>, things like: > - > -* two diff_options, one for path limiting, another for output; > -* remaining functions; > - > -(Linus, JC, Dscho) > diff --git a/revision.h b/revision.h > index 4134dc6029..983ffc0f12 100644 > --- a/revision.h > +++ b/revision.h > @@ -9,6 +9,19 @@ > #include "diff.h" > #include "commit-slab-decl.h" > > +/** > + * The revision walking API offers functions to build a list of revisions > + * and then iterate over that list. > + * > + * Calling sequence > + * ---------------- > + * > + * The walking API has a given calling sequence: first you need to initialize > + * a rev_info structure, then add revisions to control what kind of revision > + * list do you want to get, finally you can iterate over the revision list. > + * > + */ > + > /* Remember to update object flag allocation in object.h */ > #define SEEN (1u<<0) > #define UNINTERESTING (1u<<1) > @@ -306,11 +319,29 @@ struct setup_revision_opt { > #ifndef NO_THE_REPOSITORY_COMPATIBILITY_MACROS > #define init_revisions(revs, prefix) repo_init_revisions(the_repository, revs, prefix) > #endif > + > +/** > + * Initialize a rev_info structure with default values. The third parameter may > + * be NULL or can be prefix path, and then the `.prefix` variable will be set > + * to it. This is typically the first function you want to call when you want > + * to deal with a revision list. After calling this function, you are free to > + * customize options, like set `.ignore_merges` to 0 if you don't want to > + * ignore merges, and so on. > + */ > void repo_init_revisions(struct repository *r, > struct rev_info *revs, > const char *prefix); > + > +/** > + * Parse revision information, filling in the `rev_info` structure, and > + * removing the used arguments from the argument list. Returns the number > + * of arguments left that weren't recognized, which are also moved to the > + * head of the argument list. The last parameter is used in case no > + * parameter given by the first two arguments. > + */ > int setup_revisions(int argc, const char **argv, struct rev_info *revs, > struct setup_revision_opt *); > + > void parse_revision_opt(struct rev_info *revs, struct parse_opt_ctx_t *ctx, > const struct option *options, > const char * const usagestr[]); > @@ -319,9 +350,26 @@ void parse_revision_opt(struct rev_info *revs, struct parse_opt_ctx_t *ctx, > int handle_revision_arg(const char *arg, struct rev_info *revs, > int flags, unsigned revarg_opt); > > +/** > + * Reset the flags used by the revision walking api. You can use this to do > + * multiple sequential revision walks. > + */ > void reset_revision_walk(void); > + > +/** > + * Prepares the rev_info structure for a walk. You should check if it returns > + * any error (non-zero return code) and if it does not, you can start using > + * get_revision() to do the iteration. > + */ > int prepare_revision_walk(struct rev_info *revs); > + > +/** > + * Takes a pointer to a `rev_info` structure and iterates over it, returning a > + * `struct commit *` each time you call it. The end of the revision list is > + * indicated by returning a NULL pointer. > + */ > struct commit *get_revision(struct rev_info *revs); > + > char *get_revision_mark(const struct rev_info *revs, > const struct commit *commit); > void put_revision_mark(const struct rev_info *revs, > @@ -333,8 +381,19 @@ void mark_trees_uninteresting_sparse(struct repository *r, struct oidset *trees) > > void show_object_with_name(FILE *, struct object *, const char *); > > +/** > + * This function can be used if you want to add commit objects as revision > + * information. You can use the `UNINTERESTING` object flag to indicate if > + * you want to include or exclude the given commit (and commits reachable > + * from the given commit) from the revision list. > + * > + * NOTE: If you have the commits as a string list then you probably want to > + * use setup_revisions(), instead of parsing each string and using this > + * function. > + */ > void add_pending_object(struct rev_info *revs, > struct object *obj, const char *name); > + > void add_pending_oid(struct rev_info *revs, > const char *name, const struct object_id *oid, > unsigned int flags); > -- > gitgitgadget >
diff --git a/Documentation/technical/api-revision-walking.txt b/Documentation/technical/api-revision-walking.txt deleted file mode 100644 index 03f9ea6ac4..0000000000 --- a/Documentation/technical/api-revision-walking.txt +++ /dev/null @@ -1,72 +0,0 @@ -revision walking API -==================== - -The revision walking API offers functions to build a list of revisions -and then iterate over that list. - -Calling sequence ----------------- - -The walking API has a given calling sequence: first you need to -initialize a rev_info structure, then add revisions to control what kind -of revision list do you want to get, finally you can iterate over the -revision list. - -Functions ---------- - -`repo_init_revisions`:: - - Initialize a rev_info structure with default values. The third - parameter may be NULL or can be prefix path, and then the `.prefix` - variable will be set to it. This is typically the first function you - want to call when you want to deal with a revision list. After calling - this function, you are free to customize options, like set - `.ignore_merges` to 0 if you don't want to ignore merges, and so on. See - `revision.h` for a complete list of available options. - -`add_pending_object`:: - - This function can be used if you want to add commit objects as revision - information. You can use the `UNINTERESTING` object flag to indicate if - you want to include or exclude the given commit (and commits reachable - from the given commit) from the revision list. -+ -NOTE: If you have the commits as a string list then you probably want to -use setup_revisions(), instead of parsing each string and using this -function. - -`setup_revisions`:: - - Parse revision information, filling in the `rev_info` structure, and - removing the used arguments from the argument list. Returns the number - of arguments left that weren't recognized, which are also moved to the - head of the argument list. The last parameter is used in case no - parameter given by the first two arguments. - -`prepare_revision_walk`:: - - Prepares the rev_info structure for a walk. You should check if it - returns any error (non-zero return code) and if it does not, you can - start using get_revision() to do the iteration. - -`get_revision`:: - - Takes a pointer to a `rev_info` structure and iterates over it, - returning a `struct commit *` each time you call it. The end of the - revision list is indicated by returning a NULL pointer. - -`reset_revision_walk`:: - - Reset the flags used by the revision walking api. You can use - this to do multiple sequential revision walks. - -Data structures ---------------- - -Talk about <revision.h>, things like: - -* two diff_options, one for path limiting, another for output; -* remaining functions; - -(Linus, JC, Dscho) diff --git a/revision.h b/revision.h index 4134dc6029..983ffc0f12 100644 --- a/revision.h +++ b/revision.h @@ -9,6 +9,19 @@ #include "diff.h" #include "commit-slab-decl.h" +/** + * The revision walking API offers functions to build a list of revisions + * and then iterate over that list. + * + * Calling sequence + * ---------------- + * + * The walking API has a given calling sequence: first you need to initialize + * a rev_info structure, then add revisions to control what kind of revision + * list do you want to get, finally you can iterate over the revision list. + * + */ + /* Remember to update object flag allocation in object.h */ #define SEEN (1u<<0) #define UNINTERESTING (1u<<1) @@ -306,11 +319,29 @@ struct setup_revision_opt { #ifndef NO_THE_REPOSITORY_COMPATIBILITY_MACROS #define init_revisions(revs, prefix) repo_init_revisions(the_repository, revs, prefix) #endif + +/** + * Initialize a rev_info structure with default values. The third parameter may + * be NULL or can be prefix path, and then the `.prefix` variable will be set + * to it. This is typically the first function you want to call when you want + * to deal with a revision list. After calling this function, you are free to + * customize options, like set `.ignore_merges` to 0 if you don't want to + * ignore merges, and so on. + */ void repo_init_revisions(struct repository *r, struct rev_info *revs, const char *prefix); + +/** + * Parse revision information, filling in the `rev_info` structure, and + * removing the used arguments from the argument list. Returns the number + * of arguments left that weren't recognized, which are also moved to the + * head of the argument list. The last parameter is used in case no + * parameter given by the first two arguments. + */ int setup_revisions(int argc, const char **argv, struct rev_info *revs, struct setup_revision_opt *); + void parse_revision_opt(struct rev_info *revs, struct parse_opt_ctx_t *ctx, const struct option *options, const char * const usagestr[]); @@ -319,9 +350,26 @@ void parse_revision_opt(struct rev_info *revs, struct parse_opt_ctx_t *ctx, int handle_revision_arg(const char *arg, struct rev_info *revs, int flags, unsigned revarg_opt); +/** + * Reset the flags used by the revision walking api. You can use this to do + * multiple sequential revision walks. + */ void reset_revision_walk(void); + +/** + * Prepares the rev_info structure for a walk. You should check if it returns + * any error (non-zero return code) and if it does not, you can start using + * get_revision() to do the iteration. + */ int prepare_revision_walk(struct rev_info *revs); + +/** + * Takes a pointer to a `rev_info` structure and iterates over it, returning a + * `struct commit *` each time you call it. The end of the revision list is + * indicated by returning a NULL pointer. + */ struct commit *get_revision(struct rev_info *revs); + char *get_revision_mark(const struct rev_info *revs, const struct commit *commit); void put_revision_mark(const struct rev_info *revs, @@ -333,8 +381,19 @@ void mark_trees_uninteresting_sparse(struct repository *r, struct oidset *trees) void show_object_with_name(FILE *, struct object *, const char *); +/** + * This function can be used if you want to add commit objects as revision + * information. You can use the `UNINTERESTING` object flag to indicate if + * you want to include or exclude the given commit (and commits reachable + * from the given commit) from the revision list. + * + * NOTE: If you have the commits as a string list then you probably want to + * use setup_revisions(), instead of parsing each string and using this + * function. + */ void add_pending_object(struct rev_info *revs, struct object *obj, const char *name); + void add_pending_oid(struct rev_info *revs, const char *name, const struct object_id *oid, unsigned int flags);