{"thread":{"id":"44899","subject":"[PATCH] documentation: remove unfinished documentation","startedAt":"2017-01-17T20:09:54Z","lastAt":"2017-01-17T21:47:56Z","messageCount":5,"participants":["Stefan Beller","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"309544","messageId":"20170117200147.25425-1-sbeller@google.com","threadId":"44899","inReplyTo":null,"subject":"[PATCH] documentation: remove unfinished documentation","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-01-17T20:01:47Z","receivedAt":"2017-01-17T20:09:54Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"When looking for documentation for a specific function, you may be tempted\nto run\n\n git -C Documentation grep index_name_pos\n\nonly to find the file technical/api-in-core-index.txt, which doesn't\nhelp for understanding the given function. It would be better to not find\nthese functions in the documentation, such that people directly dive into\nthe code instead.\n\nSigned-off-by: Stefan Beller \n---\n\nI run into this a couple of times now, so I put this out tentatively.\n\nThanks,\nStefan\n\n Documentation/technical/api-in-core-index.txt | 21 ---------------------\n 1 file changed, 21 deletions(-)\n delete mode 100644 Documentation/technical/api-in-core-index.txt\n\ndiff --git a/Documentation/technical/api-in-core-index.txt b/Documentation/technical/api-in-core-index.txt\ndeleted file mode 100644\nindex adbdbf5d75..0000000000\n--- a/Documentation/technical/api-in-core-index.txt\n+++ /dev/null\n@@ -1,21 +0,0 @@\n-in-core index API\n-=================\n-\n-Talk about and , things like:\n-\n-* cache -> the_index macros\n-* read_index()\n-* write_index()\n-* ie_match_stat() and ie_modified(); how they are different and when to\n- use which.\n-* index_name_pos()\n-* remove_index_entry_at()\n-* remove_file_from_index()\n-* add_file_to_index()\n-* add_index_entry()\n-* refresh_index()\n-* discard_index()\n-* cache_tree_invalidate_path()\n-* cache_tree_update()\n-\n-(JC, Linus)\n-- \n2.11.0.297.g298debce27\n\n"},{"id":"309548","messageId":"xmqqpojle85c.fsf@gitster.mtv.corp.google.com","threadId":"44899","inReplyTo":"20170117200147.25425-1-sbeller@google.com","subject":"Re: [PATCH] documentation: remove unfinished documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-01-17T20:36:15Z","receivedAt":"2017-01-17T20:43:01Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stefan Beller writes:\n\n> When looking for documentation for a specific function, you may be tempted\n> to run\n>\n> git -C Documentation grep index_name_pos\n>\n> only to find the file technical/api-in-core-index.txt, which doesn't\n> help for understanding the given function. It would be better to not find\n> these functions in the documentation, such that people directly dive into\n> the code instead.\n>\n> Signed-off-by: Stefan Beller \n> ---\n>\n> I run into this a couple of times now, so I put this out tentatively.\n\nThese placeholders are meant to encourage those people who dove into\nthe code to update it, so from that point of view, I think removing\nit is backwards.\n"},{"id":"309549","messageId":"20170117204642.31514-1-sbeller@google.com","threadId":"44899","inReplyTo":"xmqqpojle85c.fsf@gitster.mtv.corp.google.com","subject":"[PATCH] document index_name_pos","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-01-17T20:46:42Z","receivedAt":"2017-01-17T20:46:51Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"Signed-off-by: Stefan Beller \n---\n\n> These placeholders are meant to encourage those people who dove into\n> the code to update it, so from that point of view, I think removing\n> it is backwards.\n\nYes, I am currently understanding and writing up documentation for\nindex_name_pos. If I recall the latest discussion where we want to have\ndocumentation, I think a quorum favored documentation in the header itself,\nc.f. strbuf.h, string-list.h for the most desired state. (Although we do have\nDocumentation/technical/api-string-list.txt as well ...)\n\nSo maybe starting like this?\n\nThanks,\nStefan\n\n cache.h | 13 +++++++++++++\n 1 file changed, 13 insertions(+)\n\ndiff --git a/cache.h b/cache.h\nindex 1b67f078dd..e168e4e073 100644\n--- a/cache.h\n+++ b/cache.h\n@@ -575,7 +575,20 @@ extern int verify_path(const char *path);\n extern int index_dir_exists(struct index_state *istate, const char *name, int namelen);\n extern void adjust_dirname_case(struct index_state *istate, char *name);\n extern struct cache_entry *index_file_exists(struct index_state *istate, const char *name, int namelen, int igncase);\n+\n+/*\n+ * Searches for an entry defined by name and namelen in the given index.\n+ * If the return value is positive (including 0) it is the position of an\n+ * exact match. If the return value is negative, the negated value minus 1 is the\n+ * position where the entry would be inserted.\n+ * Example: In the current index we have the files a,c,d:\n+ * index_name_pos(&index, \"a\", 1) -> 0\n+ * index_name_pos(&index, \"b\", 1) -> -1\n+ * index_name_pos(&index, \"c\", 1) -> 1\n+ * index_name_pos(&index, \"d\", 1) -> 2\n+ */\n extern int index_name_pos(const struct index_state *, const char *name, int namelen);\n+\n #define ADD_CACHE_OK_TO_ADD 1\t\t/* Ok to add */\n #define ADD_CACHE_OK_TO_REPLACE 2\t/* Ok to replace file/directory */\n #define ADD_CACHE_SKIP_DFCHECK 4\t/* Ok to skip DF conflict checks */\n-- \n2.11.0.297.g298debce27\n\n"},{"id":"309563","messageId":"xmqqo9z5cqh8.fsf@gitster.mtv.corp.google.com","threadId":"44899","inReplyTo":"20170117204642.31514-1-sbeller@google.com","subject":"Re: [PATCH] document index_name_pos","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-01-17T21:43:15Z","receivedAt":"2017-01-17T21:45:03Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stefan Beller writes:\n\n> Signed-off-by: Stefan Beller \n> ---\n>\n>> These placeholders are meant to encourage those people who dove into\n>> the code to update it, so from that point of view, I think removing\n>> it is backwards.\n>\n> Yes, I am currently understanding and writing up documentation for\n> index_name_pos. If I recall the latest discussion where we want to have\n> documentation, I think a quorum favored documentation in the header itself,\n> c.f. strbuf.h, string-list.h for the most desired state. (Although we do have\n> Documentation/technical/api-string-list.txt as well ...)\n>\n> So maybe starting like this?\n\nThat is very good. Let's drop that file from Documentation/technical\nand do it like this (meaning, take both patches from you).\n\nThanks.\n\n\n>\n> Thanks,\n> Stefan\n>\n> cache.h | 13 +++++++++++++\n> 1 file changed, 13 insertions(+)\n>\n> diff --git a/cache.h b/cache.h\n> index 1b67f078dd..e168e4e073 100644\n> --- a/cache.h\n> +++ b/cache.h\n> @@ -575,7 +575,20 @@ extern int verify_path(const char *path);\n> extern int index_dir_exists(struct index_state *istate, const char *name, int namelen);\n> extern void adjust_dirname_case(struct index_state *istate, char *name);\n> extern struct cache_entry *index_file_exists(struct index_state *istate, const char *name, int namelen, int igncase);\n> +\n> +/*\n> + * Searches for an entry defined by name and namelen in the given index.\n> + * If the return value is positive (including 0) it is the position of an\n> + * exact match. If the return value is negative, the negated value minus 1 is the\n> + * position where the entry would be inserted.\n> + * Example: In the current index we have the files a,c,d:\n> + * index_name_pos(&index, \"a\", 1) -> 0\n> + * index_name_pos(&index, \"b\", 1) -> -1\n> + * index_name_pos(&index, \"c\", 1) -> 1\n> + * index_name_pos(&index, \"d\", 1) -> 2\n> + */\n> extern int index_name_pos(const struct index_state *, const char *name, int namelen);\n> +\n> #define ADD_CACHE_OK_TO_ADD 1\t\t/* Ok to add */\n> #define ADD_CACHE_OK_TO_REPLACE 2\t/* Ok to replace file/directory */\n> #define ADD_CACHE_SKIP_DFCHECK 4\t/* Ok to skip DF conflict checks */\n"},{"id":"309567","messageId":"CAGZ79kbZamLJqPW-sajL4LUxbJHo_v9j0S=_nLwA30JCYmqQLQ@mail.gmail.com","threadId":"44899","inReplyTo":"xmqqo9z5cqh8.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] document index_name_pos","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-01-17T21:47:45Z","receivedAt":"2017-01-17T21:47:56Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Tue, Jan 17, 2017 at 1:43 PM, Junio C Hamano wrote:\n> Stefan Beller writes:\n>\n>> Signed-off-by: Stefan Beller \n>> ---\n>>\n>>> These placeholders are meant to encourage those people who dove into\n>>> the code to update it, so from that point of view, I think removing\n>>> it is backwards.\n>>\n>> Yes, I am currently understanding and writing up documentation for\n>> index_name_pos. If I recall the latest discussion where we want to have\n>> documentation, I think a quorum favored documentation in the header itself,\n>> c.f. strbuf.h, string-list.h for the most desired state. (Although we do have\n>> Documentation/technical/api-string-list.txt as well ...)\n>>\n>> So maybe starting like this?\n>\n> That is very good. Let's drop that file from Documentation/technical\n> and do it like this (meaning, take both patches from you).\n>\n> Thanks.\n\nThis patch is incorrect, as we need to do s/b -> -1/b -> -2/.\n(Wrong documentation is the worst)\n\nAlso we'd probably want to see more of the functions documented.\nI'll see if I can extend this into a series documenting more functions.\n\nThanks,\nStefan\n"}]}