Merge branch 'sb/in-core-index-doc' into maint

Documentation and in-code comments updates.

* sb/in-core-index-doc:
documentation: retire unfinished documentation
cache.h: document add_[file_]to_index
cache.h: document remove_index_entry_at
cache.h: document index_name_pos

diff --combined cache.h
index b14c0e8e38498f3d1dbb50f40cc5e3b484e96583,b36b4fa31b3f123daf59d56064b59bef713ed9af..5c035dae57c4dfe710802021c4b4af6b6cb1ad8b
--- 1/cache.h
--- 2/cache.h
+++ b/cache.h
@@@ -575,7 -575,26 +575,26 @@@ extern int verify_path(const char *path
  extern int index_dir_exists(struct index_state *istate, const char *name, int namelen);
  extern void adjust_dirname_case(struct index_state *istate, char *name);
  extern struct cache_entry *index_file_exists(struct index_state *istate, const char *name, int namelen, int igncase);
+ 
+ /*
+  * Searches for an entry defined by name and namelen in the given index.
+  * If the return value is positive (including 0) it is the position of an
+  * exact match. If the return value is negative, the negated value minus 1
+  * is the position where the entry would be inserted.
+  * Example: The current index consists of these files and its stages:
+  *
+  *   b#0, d#0, f#1, f#3
+  *
+  * index_name_pos(&index, "a", 1) -> -1
+  * index_name_pos(&index, "b", 1) ->  0
+  * index_name_pos(&index, "c", 1) -> -2
+  * index_name_pos(&index, "d", 1) ->  1
+  * index_name_pos(&index, "e", 1) -> -3
+  * index_name_pos(&index, "f", 1) -> -3
+  * index_name_pos(&index, "g", 1) -> -5
+  */
  extern int index_name_pos(const struct index_state *, const char *name, int namelen);
+ 
  #define ADD_CACHE_OK_TO_ADD 1         /* Ok to add */
  #define ADD_CACHE_OK_TO_REPLACE 2     /* Ok to replace file/directory */
  #define ADD_CACHE_SKIP_DFCHECK 4      /* Ok to skip DF conflict checks */
@@@ -584,7 -603,10 +603,10 @@@
  #define ADD_CACHE_KEEP_CACHE_TREE 32  /* Do not invalidate cache-tree */
  extern int add_index_entry(struct index_state *, struct cache_entry *ce, int option);
  extern void rename_index_entry_at(struct index_state *, int pos, const char *new_name);
+ 
+ /* Remove entry, return true if there are more entries to go. */
  extern int remove_index_entry_at(struct index_state *, int pos);
+ 
  extern void remove_marked_cache_entries(struct index_state *istate);
  extern int remove_file_from_index(struct index_state *, const char *path);
  #define ADD_CACHE_VERBOSE 1
@@@ -592,8 -614,18 +614,18 @@@
  #define ADD_CACHE_IGNORE_ERRORS       4
  #define ADD_CACHE_IGNORE_REMOVAL 8
  #define ADD_CACHE_INTENT 16
+ /*
+  * These two are used to add the contents of the file at path
+  * to the index, marking the working tree up-to-date by storing
+  * the cached stat info in the resulting cache entry.  A caller
+  * that has already run lstat(2) on the path can call
+  * add_to_index(), and all others can call add_file_to_index();
+  * the latter will do necessary lstat(2) internally before
+  * calling the former.
+  */
  extern int add_to_index(struct index_state *, const char *path, struct stat *, int flags);
  extern int add_file_to_index(struct index_state *, const char *path, int flags);
+ 
  extern struct cache_entry *make_cache_entry(unsigned int mode, const unsigned char *sha1, const char *path, int stage, unsigned int refresh_options);
  extern int chmod_index_entry(struct index_state *, struct cache_entry *ce, char flip);
  extern int ce_same_name(const struct cache_entry *a, const struct cache_entry *b);
@@@ -670,7 -702,7 +702,7 @@@ extern const char *git_attributes_file
  extern const char *git_hooks_path;
  extern int zlib_compression_level;
  extern int core_compression_level;
 -extern int core_compression_seen;
 +extern int pack_compression_level;
  extern size_t packed_git_window_size;
  extern size_t packed_git_limit;
  extern size_t delta_base_cache_limit;