git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCHv3 4/4] documentation: retire unfinished documentation

From
Stefan Beller <sbeller@google.com>
Date
Jan 19, 2017, 03:18 UTC
Message-ID
<20170119031854.4570-5-sbeller@google.com>
In-Reply-To
<20170119031854.4570-1-sbeller@google.com>

When looking for documentation for a specific function, you may be tempted to run

  git -C Documentation grep index_name_pos

only to find the file technical/api-in-core-index.txt, which doesn't help for understanding the given function. It would be better to not find these functions in the documentation, such that people directly dive into the code instead.

In the previous patches we have documented
* index_name_pos()
* remove_index_entry_at()
* add_[file_]to_index()
in cache.h
We already have documentation for:
* add_index_entry()
* read_index()
Which leaves us with a TODO for:
* cache -> the_index macros
* refresh_index()
* discard_index()
* ie_match_stat() and ie_modified(); how they are different and when to
  use which.
* write_index() that was renamed to write_locked_index
* cache_tree_invalidate_path()
* cache_tree_update()
Signed-off-by: Stefan Beller <sbeller@google.com>
---
 Documentation/technical/api-in-core-index.txt | 21 ---------------------
 1 file changed, 21 deletions(-)
 delete mode 100644 Documentation/technical/api-in-core-index.txt
diff --git a/Documentation/technical/api-in-core-index.txt b/Documentation/technical/api-in-core-index.txt
deleted file mode 100644
index adbdbf5d75..0000000000
--- a/Documentation/technical/api-in-core-index.txt
+++ /dev/null
@@ -1,21 +0,0 @@
-in-core index API
-=================
-
-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()
-* add_index_entry()
-* refresh_index()
-* discard_index()
-* cache_tree_invalidate_path()
-* cache_tree_update()
-
-(JC, Linus)
-- 
2.11.0.299.g762782ba8a
Previous: Stefan BellerNext: Stefan Beller
Message 23 of 25 in “start documenting core functions”
  1. 0/4 start documenting core functionsStefan Beller, Jan 17, 2017
  2. 2/4 remove_index_entry_at: move documentation to cache.hStefan Beller, Jan 17, 2017
  3. Junio C HamanoJan 18, 2017
  4. Stefan BellerJan 18, 2017
  5. 1/4 document index_name_posStefan Beller, Jan 17, 2017
  6. Junio C HamanoJan 18, 2017
  7. Stefan BellerJan 18, 2017
  8. 3/4 document add_[file_]to_indexStefan Beller, Jan 17, 2017
  9. Junio C HamanoJan 18, 2017
  10. Stefan BellerJan 18, 2017
  11. 4/4 documentation: retire unfinished documentationStefan Beller, Jan 17, 2017
  12. Junio C HamanoJan 18, 2017
  13. 0/4 start documenting core functionsStefan Beller, Jan 18, 2017
  14. 2/4 cache.h: document remove_index_entry_atStefan Beller, Jan 18, 2017
  15. 3/4 cache.h: document add_[file_]to_indexStefan Beller, Jan 18, 2017
  16. Brandon WilliamsJan 19, 2017
  17. Stefan BellerJan 19, 2017
  18. 1/4 cache.h: document index_name_posStefan Beller, Jan 18, 2017
  19. 0/4 start documenting core functionsStefan Beller, Jan 19, 2017
  20. 1/4 cache.h: document index_name_posStefan Beller, Jan 19, 2017
  21. Junio C HamanoJan 19, 2017
  22. 2/4 cache.h: document remove_index_entry_atStefan Beller, Jan 19, 2017
  23. 4/4 documentation: retire unfinished documentationStefan Beller, Jan 19, 2017
  24. 3/4 cache.h: document add_[file_]to_indexStefan Beller, Jan 19, 2017
  25. 4/4 documentation: retire unfinished documentationStefan Beller, Jan 18, 2017

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.