git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: "Heba Waly via GitGitGadget" <gitgitgadget@gmail.com>
To: git@vger.kernel.org
Cc: Heba Waly <heba.waly@gmail.com>,
	Junio C Hamano <gitster@pobox.com>,
	Heba Waly <heba.waly@gmail.com>
Subject: [PATCH v2 09/20] revision: move doc to revision.h
Date: Wed, 06 Nov 2019 09:59:36 +0000	[thread overview]
Message-ID: <acd6287ced1f0c5d113a728c7321981ff985a133.1573034387.git.gitgitgadget@gmail.com> (raw)
In-Reply-To: <pull.434.v2.git.1573034387.gitgitgadget@gmail.com>

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.

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


  parent reply	other threads:[~2019-11-06  9:59 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
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   ` Heba Waly via GitGitGadget [this message]
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

  List information: http://vger.kernel.org/majordomo-info.html

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

  git send-email \
    --in-reply-to=acd6287ced1f0c5d113a728c7321981ff985a133.1573034387.git.gitgitgadget@gmail.com \
    --to=gitgitgadget@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=heba.waly@gmail.com \
    /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
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

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 read-only IMAP folder(s) and NNTP newsgroup(s).