Re: [PATCH] Revision walking documentation: document most important functions

[Junio C Hamano <gitster@pobox.com>]

Miklos Vajna <vmiklos@frugalware.org> writes:

> Unfortunately the list is not complete, but includes the essential ones.
> ...
> 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.

It's a good start.  Thanks.

>  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.

I think this paragraph is easier to read if it is in its own subsection
"Calling Sequence" (see api-diff.txt for an example).

> +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.

Traversal options are numerous and complex, so I agree that it makes sense
to refer the reader elsewhere.  We can start with "revision.h", and extend
this documentation by adding a separate section on it.

> +`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

s/positive/non-zero/;