git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Emily Shaffer <emilyshaffer@google.com>
To: Heba Waly via GitGitGadget <gitgitgadget@gmail.com>
Cc: git@vger.kernel.org, Heba Waly <heba.waly@gmail.com>,
	Junio C Hamano <gitster@pobox.com>
Subject: Re: [PATCH 09/10] revision: move doc to revision.h
Date: Tue, 29 Oct 2019 16:57:36 -0700	[thread overview]
Message-ID: <20191029235736.GB229589@google.com> (raw)
In-Reply-To: <afab6d5f4ed8cbe8e6dcba9a50282a471b542b13.1572343246.git.gitgitgadget@gmail.com>

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
> 

  reply	other threads:[~2019-10-29 23:57 UTC|newest]

Thread overview: 123+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-10-29 10:00 [PATCH 00/10] [Outreachy] Move doc to header files Heba Waly via GitGitGadget
2019-10-29 10:00 ` [PATCH 01/10] diff: move doc to diff.h and diffcore.h Heba Waly via GitGitGadget
2019-10-29 10:00 ` [PATCH 02/10] dir: move doc to dir.h Heba Waly via GitGitGadget
2019-10-29 10:00 ` [PATCH 03/10] graph: move doc to graph.h and graph.c Heba Waly via GitGitGadget
2019-10-29 10:00 ` [PATCH 04/10] merge: move doc to ll-merge.h Heba Waly via GitGitGadget
2019-10-30 22:09   ` Elijah Newren
2019-10-31 19:35     ` Heba Waly
2019-11-02  4:28     ` Junio C Hamano
2019-10-29 10:00 ` [PATCH 05/10] sha1-array: move doc to sha1-array.h Heba Waly via GitGitGadget
2019-10-29 10:00 ` [PATCH 06/10] remote: move doc to remote.h and refspec.h Heba Waly via GitGitGadget
2019-10-29 10:00 ` [PATCH 07/10] refs: move doc to refs.h Heba Waly via GitGitGadget
2019-10-29 10:00 ` [PATCH 08/10] attr: move doc to attr.h Heba Waly via GitGitGadget
2019-10-29 10:00 ` [PATCH 09/10] revision: move doc to revision.h Heba Waly via GitGitGadget
2019-10-29 23:57   ` Emily Shaffer [this message]
2019-10-29 10:00 ` [PATCH 10/10] pathspec: move doc to pathspec.h Heba Waly via GitGitGadget
2019-11-06  9:59 ` [PATCH v2 00/20] [Outreachy] Move doc to header files Heba Waly via GitGitGadget
2019-11-06  9:59   ` [PATCH v2 01/20] diff: move doc to diff.h and diffcore.h Heba Waly via GitGitGadget
2019-11-06  9:59   ` [PATCH v2 02/20] dir: move doc to dir.h Heba Waly via GitGitGadget
2019-11-07  1:16     ` Emily Shaffer
2019-11-11  0:20       ` Heba Waly
2019-11-06  9:59   ` [PATCH v2 03/20] graph: move doc to graph.h and graph.c Heba Waly via GitGitGadget
2019-11-06  9:59   ` [PATCH v2 04/20] merge: move doc to ll-merge.h Heba Waly via GitGitGadget
2019-11-06  9:59   ` [PATCH v2 05/20] sha1-array: move doc to sha1-array.h Heba Waly via GitGitGadget
2019-11-06  9:59   ` [PATCH v2 06/20] remote: move doc to remote.h and refspec.h Heba Waly via GitGitGadget
2019-11-06  9:59   ` [PATCH v2 07/20] refs: move doc to refs.h Heba Waly via GitGitGadget
2019-11-06  9:59   ` [PATCH v2 08/20] attr: move doc to attr.h Heba Waly via GitGitGadget
2019-11-06  9:59   ` [PATCH v2 09/20] revision: move doc to revision.h Heba Waly via GitGitGadget
2019-11-06  9:59   ` [PATCH v2 10/20] pathspec: move doc to pathspec.h Heba Waly via GitGitGadget
2019-11-07  1:26     ` Emily Shaffer
2019-11-10  1:40       ` Heba Waly
2019-11-06  9:59   ` [PATCH v2 11/20] sigchain: move doc to sigchain.h Heba Waly via GitGitGadget
2019-11-06 22:03     ` Emily Shaffer
2019-11-11  1:04       ` Heba Waly
2019-11-06  9:59   ` [PATCH v2 12/20] cache: move doc to cache.h Heba Waly via GitGitGadget
2019-11-06 22:04     ` Emily Shaffer
2019-11-06  9:59   ` [PATCH v2 13/20] argv-array: move doc to argv-array.h Heba Waly via GitGitGadget
2019-11-06  9:59   ` [PATCH v2 14/20] credential: move doc to credential.h Heba Waly via GitGitGadget
2019-11-06  9:59   ` [PATCH v2 15/20] parse-options: move doc to parse-options.h Heba Waly via GitGitGadget
2019-11-11  2:45     ` Junio C Hamano
2019-11-11 21:38       ` Heba Waly
2019-11-12  5:57         ` Junio C Hamano
2019-11-15  9:55           ` Heba Waly
2019-11-15 11:37             ` Junio C Hamano
2019-11-15 23:28               ` Emily Shaffer
2019-11-17 11:34                 ` Heba Waly
2019-11-06  9:59   ` [PATCH v2 16/20] run-command: move doc to run-command.h Heba Waly via GitGitGadget
2019-11-06  9:59   ` [PATCH v2 17/20] trace: move doc to trace.h Heba Waly via GitGitGadget
2019-11-07  1:32     ` Emily Shaffer
2019-11-06  9:59   ` [PATCH v2 18/20] tree-walk: move doc to tree-walk.h Heba Waly via GitGitGadget
2019-11-06  9:59   ` [PATCH v2 19/20] submodule-config: move doc to submodule-config.h Heba Waly via GitGitGadget
2019-11-06  9:59   ` [PATCH v2 20/20] trace2: move doc to trace2.h Heba Waly via GitGitGadget
2019-11-11 21:27   ` [PATCH v3 00/21] [Outreachy] Move doc to header files Heba Waly via GitGitGadget
2019-11-11 21:27     ` [PATCH v3 01/21] diff: move doc to diff.h and diffcore.h Heba Waly via GitGitGadget
2019-11-12  7:20       ` Junio C Hamano
2019-11-14 12:22         ` Heba Waly
2019-11-11 21:27     ` [PATCH v3 02/21] dir: move doc to dir.h Heba Waly via GitGitGadget
2019-11-11 21:27     ` [PATCH v3 03/21] graph: move doc to graph.h and graph.c Heba Waly via GitGitGadget
2019-11-11 21:27     ` [PATCH v3 04/21] merge: move doc to ll-merge.h Heba Waly via GitGitGadget
2019-11-11 21:27     ` [PATCH v3 05/21] sha1-array: move doc to sha1-array.h Heba Waly via GitGitGadget
2019-11-11 21:27     ` [PATCH v3 06/21] remote: move doc to remote.h and refspec.h Heba Waly via GitGitGadget
2019-11-11 21:27     ` [PATCH v3 07/21] refs: move doc to refs.h Heba Waly via GitGitGadget
2019-11-11 21:27     ` [PATCH v3 08/21] attr: move doc to attr.h Heba Waly via GitGitGadget
2019-11-11 21:27     ` [PATCH v3 09/21] revision: move doc to revision.h Heba Waly via GitGitGadget
2019-11-11 21:27     ` [PATCH v3 10/21] pathspec: move doc to pathspec.h Heba Waly via GitGitGadget
2019-11-11 21:27     ` [PATCH v3 11/21] sigchain: move doc to sigchain.h Heba Waly via GitGitGadget
2019-11-11 21:27     ` [PATCH v3 12/21] cache: move doc to cache.h Heba Waly via GitGitGadget
2019-11-12  7:05       ` Junio C Hamano
2019-11-14 10:14         ` Heba Waly
2019-11-11 21:27     ` [PATCH v3 13/21] argv-array: move doc to argv-array.h Heba Waly via GitGitGadget
2019-11-11 21:27     ` [PATCH v3 14/21] credential: move doc to credential.h Heba Waly via GitGitGadget
2019-11-11 21:27     ` [PATCH v3 15/21] parse-options: move doc to parse-options.h Heba Waly via GitGitGadget
2019-11-11 21:27     ` [PATCH v3 16/21] run-command: move doc to run-command.h Heba Waly via GitGitGadget
2019-11-11 21:28     ` [PATCH v3 17/21] trace: move doc to trace.h Heba Waly via GitGitGadget
2019-11-11 21:28     ` [PATCH v3 18/21] tree-walk: move doc to tree-walk.h Heba Waly via GitGitGadget
2019-11-11 21:28     ` [PATCH v3 19/21] submodule-config: move doc to submodule-config.h Heba Waly via GitGitGadget
2019-11-11 21:28     ` [PATCH v3 20/21] trace2: move doc to trace2.h Heba Waly via GitGitGadget
2019-11-12  7:02       ` Junio C Hamano
2019-11-14 10:30         ` Heba Waly
2019-11-11 21:28     ` [PATCH v3 21/21] api-index: remove api doc index files Heba Waly via GitGitGadget
2019-11-15  9:53     ` [PATCH v4 00/21] [Outreachy] Move doc to header files Heba Waly via GitGitGadget
2019-11-15  9:53       ` [PATCH v4 01/21] diff: move doc to diff.h and diffcore.h Heba Waly via GitGitGadget
2019-11-15  9:53       ` [PATCH v4 02/21] dir: move doc to dir.h Heba Waly via GitGitGadget
2019-11-15  9:53       ` [PATCH v4 03/21] graph: move doc to graph.h and graph.c Heba Waly via GitGitGadget
2019-11-15  9:53       ` [PATCH v4 04/21] merge: move doc to ll-merge.h Heba Waly via GitGitGadget
2019-11-15  9:53       ` [PATCH v4 05/21] sha1-array: move doc to sha1-array.h Heba Waly via GitGitGadget
2019-11-15  9:53       ` [PATCH v4 06/21] remote: move doc to remote.h and refspec.h Heba Waly via GitGitGadget
2019-11-15  9:53       ` [PATCH v4 07/21] refs: move doc to refs.h Heba Waly via GitGitGadget
2019-11-15  9:53       ` [PATCH v4 08/21] attr: move doc to attr.h Heba Waly via GitGitGadget
2019-11-15  9:53       ` [PATCH v4 09/21] revision: move doc to revision.h Heba Waly via GitGitGadget
2019-11-15  9:53       ` [PATCH v4 10/21] pathspec: move doc to pathspec.h Heba Waly via GitGitGadget
2019-11-15  9:53       ` [PATCH v4 11/21] sigchain: move doc to sigchain.h Heba Waly via GitGitGadget
2019-11-15  9:53       ` [PATCH v4 12/21] cache: move doc to cache.h Heba Waly via GitGitGadget
2019-11-15  9:53       ` [PATCH v4 13/21] argv-array: move doc to argv-array.h Heba Waly via GitGitGadget
2019-11-15  9:53       ` [PATCH v4 14/21] credential: move doc to credential.h Heba Waly via GitGitGadget
2019-11-15  9:53       ` [PATCH v4 15/21] parse-options: move doc to parse-options.h Heba Waly via GitGitGadget
2019-11-15  9:53       ` [PATCH v4 16/21] run-command: move doc to run-command.h Heba Waly via GitGitGadget
2019-11-15  9:53       ` [PATCH v4 17/21] trace: move doc to trace.h Heba Waly via GitGitGadget
2019-11-15  9:53       ` [PATCH v4 18/21] tree-walk: move doc to tree-walk.h Heba Waly via GitGitGadget
2019-11-15  9:53       ` [PATCH v4 19/21] submodule-config: move doc to submodule-config.h Heba Waly via GitGitGadget
2019-11-15  9:53       ` [PATCH v4 20/21] trace2: move doc to trace2.h Heba Waly via GitGitGadget
2019-11-15  9:53       ` [PATCH v4 21/21] api-index: remove api doc index files Heba Waly via GitGitGadget
2019-11-17 21:04       ` [PATCH v5 00/21] [Outreachy] Move doc to header files Heba Waly via GitGitGadget
2019-11-17 21:04         ` [PATCH v5 01/21] diff: move doc to diff.h and diffcore.h Heba Waly via GitGitGadget
2019-11-17 21:04         ` [PATCH v5 02/21] dir: move doc to dir.h Heba Waly via GitGitGadget
2019-11-17 21:04         ` [PATCH v5 03/21] graph: move doc to graph.h and graph.c Heba Waly via GitGitGadget
2019-11-17 21:04         ` [PATCH v5 04/21] merge: move doc to ll-merge.h Heba Waly via GitGitGadget
2019-11-17 21:04         ` [PATCH v5 05/21] sha1-array: move doc to sha1-array.h Heba Waly via GitGitGadget
2019-11-17 21:04         ` [PATCH v5 06/21] remote: move doc to remote.h and refspec.h Heba Waly via GitGitGadget
2019-11-17 21:04         ` [PATCH v5 07/21] refs: move doc to refs.h Heba Waly via GitGitGadget
2019-11-17 21:04         ` [PATCH v5 08/21] attr: move doc to attr.h Heba Waly via GitGitGadget
2019-11-17 21:04         ` [PATCH v5 09/21] revision: move doc to revision.h Heba Waly via GitGitGadget
2019-11-17 21:04         ` [PATCH v5 10/21] pathspec: move doc to pathspec.h Heba Waly via GitGitGadget
2019-11-17 21:04         ` [PATCH v5 11/21] sigchain: move doc to sigchain.h Heba Waly via GitGitGadget
2019-11-17 21:04         ` [PATCH v5 12/21] cache: move doc to cache.h Heba Waly via GitGitGadget
2019-11-17 21:04         ` [PATCH v5 13/21] argv-array: move doc to argv-array.h Heba Waly via GitGitGadget
2019-11-17 21:04         ` [PATCH v5 14/21] credential: move doc to credential.h Heba Waly via GitGitGadget
2019-11-17 21:04         ` [PATCH v5 15/21] parse-options: add link to doc file in parse-options.h Heba Waly via GitGitGadget
2019-11-17 21:04         ` [PATCH v5 16/21] run-command: move doc to run-command.h Heba Waly via GitGitGadget
2019-11-17 21:04         ` [PATCH v5 17/21] trace: move doc to trace.h Heba Waly via GitGitGadget
2019-11-17 21:04         ` [PATCH v5 18/21] tree-walk: move doc to tree-walk.h Heba Waly via GitGitGadget
2019-11-17 21:04         ` [PATCH v5 19/21] submodule-config: move doc to submodule-config.h Heba Waly via GitGitGadget
2019-11-17 21:04         ` [PATCH v5 20/21] trace2: move doc to trace2.h Heba Waly via GitGitGadget
2019-11-17 21:05         ` [PATCH v5 21/21] api-index: remove api doc index files Heba Waly via GitGitGadget

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20191029235736.GB229589@google.com \
    --to=emilyshaffer@google.com \
    --cc=git@vger.kernel.org \
    --cc=gitgitgadget@gmail.com \
    --cc=gitster@pobox.com \
    --cc=heba.waly@gmail.com \
    --subject='Re: [PATCH 09/10] revision: move doc to revision.h' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).