Re: [PATCH] argv-iter: new module

[Bruno Haible]

Hi Jim,

For a module that is to be used by several package, some more documentation
is needed IMO. From the comments outside of functions that are present, I can
only get a vague impression that the module is about "Iterate over arguments
from argv or --files0-from=FILE" and that file has is supposed to contain
NUL-delimited items.

Specifically, the questions that prevent from using the API are:

- What does the type 'struct argv_iterator' stand for?
- argv_iter_err appears to be some error code type. What do AI_ERR_MEM and
  AI_ERR_READ mean?
- What does argv_iter_init_argv do?
- Can the contents of 'argv' be freed while the result of argv_iter_init_argv
  is still in use?
- About argv_iter_init_stream? "Initialize to read from the stream" What
  is being initialized? The return value or some undocumented hidden state?
- Still about argv_iter_init_stream: "The input is expected to contain a
  list of NUL-delimited tokens". What happens if the input starts with a
  NULL? Or when it ends with a non-NULL byte? In other words, is it really
  "NUL-delimited tokens" or "NUL-terminated tokens"?
- Still about argv_iter_init_stream: Does this function close the stream,
  or is it the caller's duty?
- What does argv_iter do?
- Is the argv_iter result freshly allocated, i.e. must the caller free it?
- What does argv_iter_n_args do?
- What does argv_iter_free do? Does it free the original 'char **argv'
  argument and/or close the stream?

About the unit test:

> +#define STREQ(s1, s2) ((strcmp (s1, s2) == 0))

What is the reason for the extra parentheses? Is some gcc warning avoided
by this?

Bruno