Merge branch 'hw/doc-in-header'

* hw/doc-in-header:
  trace2: move doc to trace2.h
  submodule-config: move doc to submodule-config.h
  tree-walk: move doc to tree-walk.h
  trace: move doc to trace.h
  run-command: move doc to run-command.h
  parse-options: add link to doc file in parse-options.h
  credential: move doc to credential.h
  argv-array: move doc to argv-array.h
  cache: move doc to cache.h
  sigchain: move doc to sigchain.h
  pathspec: move doc to pathspec.h
  revision: move doc to revision.h
  attr: move doc to attr.h
  refs: move doc to refs.h
  remote: move doc to remote.h and refspec.h
  sha1-array: move doc to sha1-array.h
  merge: move doc to ll-merge.h
  graph: move doc to graph.h and graph.c
  dir: move doc to dir.h
  diff: move doc to diff.h and diffcore.h

diff --cc Documentation/technical/api-trace2.txt
Simple merge

diff --cc cache.h
Simple merge

diff --cc diff.h
Simple merge

diff --cc dir.c
Simple merge

diff --cc graph.c
Simple merge

diff --cc parse-options.h
Simple merge

diff --cc pathspec.h
index a27dc81ba214f3ed553ff249494a93efba7783bb,f3ee8d98715efbae2110d1b956940cada13dd670..454ce364fac7767a78c3d712fb4f82c448f88f33
--- 1/pathspec.h
--- 2/pathspec.h
+++ b/pathspec.h
@@@ -85,16 -117,7 +117,17 @@@ void parse_pathspec(struct pathspec *pa
                    unsigned flags,
                    const char *prefix,
                    const char **args);
 +/*
 + * Same as parse_pathspec() but uses file as input.
 + * When 'file' is exactly "-" it uses 'stdin' instead.
 + */
 +void parse_pathspec_file(struct pathspec *pathspec,
 +                       unsigned magic_mask,
 +                       unsigned flags,
 +                       const char *prefix,
 +                       const char *file,
 +                       int nul_term_line);
+ 
  void copy_pathspec(struct pathspec *dst, const struct pathspec *src);
  void clear_pathspec(struct pathspec *);
  

diff --cc revision.h
index addd69410bb0ce22dede6c0ff43fccf8b44e7e36,983ffc0f12cdb8f7748f4b995c9c0a2cc91b76d5..a1a804bd3d6ce7ef1f65f2d270f4a0378969fc93
--- 1/revision.h
--- 2/revision.h
+++ b/revision.h
@@@ -319,11 -350,28 +350,28 @@@ void parse_revision_opt(struct rev_inf
  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);
+ 
 +const char *get_revision_mark(const struct rev_info *revs,
 +                            const struct commit *commit);
  void put_revision_mark(const struct rev_info *revs,
                       const struct commit *commit);