On Aug 18, 2013, at 3:41 PM, Thomas Gummerer wrote:
Add documentation for the index reading api. This also includes
documentation for the new api functions introduced in the next patch.
Helped-by: Nguyễn Thái Ngọc Duy pclo...@gmail.com
Signed-off-by: Thomas Gummerer t.gumme...@gmail.com
---
Documentation/technical/api-in-core-index.txt | 54 +--
1 file changed, 50 insertions(+), 4 deletions(-)
diff --git a/Documentation/technical/api-in-core-index.txt
b/Documentation/technical/api-in-core-index.txt
index adbdbf5..9b8c37c 100644
--- a/Documentation/technical/api-in-core-index.txt
+++ b/Documentation/technical/api-in-core-index.txt
@@ -1,14 +1,60 @@
in-core index API
=
+Reading API
+---
+
+`cache`::
+
+ An array of cache entries. This is used to access the cache
+ entries directly. Use `index_name_pos` to search for the
+ index of a specific cache entry.
+
+`read_index_filtered`::
+
+ Read a part of the index, filtered by the pathspec given in
+ the opts. The function may load more than necessary, so the
+ caller still responsible to apply filters appropriately. The
Grammatical nit: ...the caller is still responsible for applying…
+ filtering is only done for performance reasons, as it's
+ possible to only read part of the index when the on-disk
+ format is index-v5.
+
+ To iterate only over the entries that match the pathspec, use
+ the for_each_index_entry function.
+
+`read_index`::
+
+ Read the whole index file from disk.
+
+`index_name_pos`::
+
+ Find a cache_entry with name in the index. Returns pos if an
+ entry is matched exactly and -1-pos if an entry is matched
+ partially.
+ e.g.
+ index:
+ file1
+ file2
+ path/file1
+ zzz
+
+ index_name_pos(path/file1, 10) returns 2, while
+ index_name_pos(path, 4) returns -3
A couple of these entries won't format correctly. You may want to squash in
something like this (sans whitespace damage):
--8--
diff --git a/Documentation/technical/api-in-core-index.txt
b/Documentation/technical/api-in-core-index.txt
index 9b8c37c..d2518c8 100644
--- a/Documentation/technical/api-in-core-index.txt
+++ b/Documentation/technical/api-in-core-index.txt
@@ -18,9 +18,9 @@ Reading API
filtering is only done for performance reasons, as it's
possible to only read part of the index when the on-disk
format is index-v5.
-
- To iterate only over the entries that match the pathspec, use
- the for_each_index_entry function.
++
+To iterate only over the entries that match the pathspec, use
+the for_each_index_entry function.
`read_index`::
@@ -30,16 +30,18 @@ Reading API
Find a cache_entry with name in the index. Returns pos if an
entry is matched exactly and -1-pos if an entry is matched
- partially.
- e.g.
- index:
+ partially. e.g.
++
+
+index:
file1
file2
path/file1
zzz
-
- index_name_pos(path/file1, 10) returns 2, while
- index_name_pos(path, 4) returns -3
+
++
+`index_name_pos(path/file1, 10)` returns 2, while
+`index_name_pos(path, 4)` returns -3
`for_each_index_entry`::
--
1.8.4.rc3.500.gc3113b0
--8--
+
+`for_each_index_entry`::
+
+ Iterates over all cache_entries in the index filtered by
+ filter_opts in the index_state. For each cache entry fn is
+ executed with cb_data as callback data. From within the loop
+ do `return 0` to continue, or `return 1` to break the loop.
+
+TODO
+
Talk about read-cache.c and cache-tree.c, things like:
-* cache - the_index macros
-* read_index()
* write_index()
* ie_match_stat() and ie_modified(); how they are different and when to
use which.
-* index_name_pos()
* remove_index_entry_at()
* remove_file_from_index()
* add_file_to_index()
@@ -18,4 +64,4 @@ Talk about read-cache.c and cache-tree.c, things like:
* cache_tree_invalidate_path()
* cache_tree_update()
-(JC, Linus)
+(JC, Linus, Thomas Gummerer)
--
1.8.3.4.1231.g9fbf354.dirty
--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
