[PATCH] Revision walking documentation: document most important functions

[Miklos Vajna <vmiklos@frugalware.org>]

Unfortunately the list is not complete, but includes the essential ones.

Signed-off-by: Miklos Vajna <vmiklos@frugalware.org>
---

On Thu, May 29, 2008 at 11:35:16AM -0700, Junio C Hamano <gitster@pobox.com> wrote:
> I do not want to apply a patch _from you_ to that file unless it
> actually
> adds meat to the description --- I know you know git better than doing
> just a typofix to a placeholder.

Here is a start. To be honest I never used the functions I did not
document, so I don't have too much idea what they do (not counting
reading the source ;-) ), so I thought it's better if I leave them
excluded from the list.

> Also why did I have to fix my To: header when I tried to respond to
> your
> message?

Hm, I sent the patch using git-send-email, adding the Cc line manually
and having your address in sendemail.to, so I don't know exactly what
can be special in this setup.

 Documentation/technical/api-revision-walking.txt |   57 +++++++++++++++++++++-
 1 files changed, 56 insertions(+), 1 deletions(-)

diff --git a/Documentation/technical/api-revision-walking.txt b/Documentation/technical/api-revision-walking.txt
index 01a2455..f073ee3 100644
--- a/Documentation/technical/api-revision-walking.txt
+++ b/Documentation/technical/api-revision-walking.txt
@@ -1,9 +1,64 @@
 revision walking API
 ====================
 
+The revision walking API offers functions to build a list of revisions
+and then iterate over that list.
+
+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
+---------
+
+`init_revisions`::
+
+	Initialize a rev_info structure with default values. The second
+	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 (positive 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.
+
+Data structures
+---------------
+
 Talk about <revision.h>, things like:
 
 * two diff_options, one for path limiting, another for output;
-* calling sequence: init_revisions(), setup_revsions(), get_revision();
+* remaining functions;
 
 (Linus, JC, Dscho)
-- 
1.5.6.rc0.dirty