On Tue, Oct 29, 2019 at 10:00:45AM +0000, Heba Waly via GitGitGadget wrote:
> From: Heba Waly <heba.waly@xxxxxxxxx>
>
> 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@xxxxxxxxxx>
>
> Signed-off-by: Heba Waly <heba.waly@xxxxxxxxx>
> ---
> .../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
>
