# [PATCH] documentation: remove unfinished documentation 5 messages from 2017-01-17 to 2017-01-17. Participants: Stefan Beller, Junio C Hamano. Thread: https://gitlist.dev/t/44899 ## Stefan Beller, 2017-01-17 20:01 Subject: [PATCH] documentation: remove unfinished documentation Message-ID: <20170117200147.25425-1-sbeller@google.com> URL: https://gitlist.dev/e/20170117200147.25425-1-sbeller%40google.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. Signed-off-by: Stefan Beller --- I run into this a couple of times now, so I put this out tentatively. Thanks, Stefan 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 and , 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.297.g298debce27 ``` ## Junio C Hamano, 2017-01-17 20:36 Subject: Re: [PATCH] documentation: remove unfinished documentation Message-ID: URL: https://gitlist.dev/e/xmqqpojle85c.fsf%40gitster.mtv.corp.google.com In-Reply-To: <20170117200147.25425-1-sbeller@google.com> ``` Stefan Beller writes: > 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. > > Signed-off-by: Stefan Beller > --- > > I run into this a couple of times now, so I put this out tentatively. These placeholders are meant to encourage those people who dove into the code to update it, so from that point of view, I think removing it is backwards. ``` ## Stefan Beller, 2017-01-17 20:46 Subject: [PATCH] document index_name_pos Message-ID: <20170117204642.31514-1-sbeller@google.com> URL: https://gitlist.dev/e/20170117204642.31514-1-sbeller%40google.com In-Reply-To: ``` Signed-off-by: Stefan Beller --- > These placeholders are meant to encourage those people who dove into > the code to update it, so from that point of view, I think removing > it is backwards. Yes, I am currently understanding and writing up documentation for index_name_pos. If I recall the latest discussion where we want to have documentation, I think a quorum favored documentation in the header itself, c.f. strbuf.h, string-list.h for the most desired state. (Although we do have Documentation/technical/api-string-list.txt as well ...) So maybe starting like this? Thanks, Stefan cache.h | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/cache.h b/cache.h index 1b67f078dd..e168e4e073 100644 --- a/cache.h +++ b/cache.h @@ -575,7 +575,20 @@ 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: In the current index we have the files a,c,d: + * index_name_pos(&index, "a", 1) -> 0 + * index_name_pos(&index, "b", 1) -> -1 + * index_name_pos(&index, "c", 1) -> 1 + * index_name_pos(&index, "d", 1) -> 2 + */ 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 */ -- 2.11.0.297.g298debce27 ``` ## Junio C Hamano, 2017-01-17 21:43 Subject: Re: [PATCH] document index_name_pos Message-ID: URL: https://gitlist.dev/e/xmqqo9z5cqh8.fsf%40gitster.mtv.corp.google.com In-Reply-To: <20170117204642.31514-1-sbeller@google.com> ``` Stefan Beller writes: > Signed-off-by: Stefan Beller > --- > >> These placeholders are meant to encourage those people who dove into >> the code to update it, so from that point of view, I think removing >> it is backwards. > > Yes, I am currently understanding and writing up documentation for > index_name_pos. If I recall the latest discussion where we want to have > documentation, I think a quorum favored documentation in the header itself, > c.f. strbuf.h, string-list.h for the most desired state. (Although we do have > Documentation/technical/api-string-list.txt as well ...) > > So maybe starting like this? That is very good. Let's drop that file from Documentation/technical and do it like this (meaning, take both patches from you). Thanks. > > Thanks, > Stefan > > cache.h | 13 +++++++++++++ > 1 file changed, 13 insertions(+) > > diff --git a/cache.h b/cache.h > index 1b67f078dd..e168e4e073 100644 > --- a/cache.h > +++ b/cache.h > @@ -575,7 +575,20 @@ 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: In the current index we have the files a,c,d: > + * index_name_pos(&index, "a", 1) -> 0 > + * index_name_pos(&index, "b", 1) -> -1 > + * index_name_pos(&index, "c", 1) -> 1 > + * index_name_pos(&index, "d", 1) -> 2 > + */ > 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 */ ``` ## Stefan Beller, 2017-01-17 21:47 Subject: Re: [PATCH] document index_name_pos Message-ID: URL: https://gitlist.dev/e/CAGZ79kbZamLJqPW-sajL4LUxbJHo_v9j0S%3D_nLwA30JCYmqQLQ%40mail.gmail.com In-Reply-To: ``` On Tue, Jan 17, 2017 at 1:43 PM, Junio C Hamano wrote: > Stefan Beller writes: > >> Signed-off-by: Stefan Beller >> --- >> >>> These placeholders are meant to encourage those people who dove into >>> the code to update it, so from that point of view, I think removing >>> it is backwards. >> >> Yes, I am currently understanding and writing up documentation for >> index_name_pos. If I recall the latest discussion where we want to have >> documentation, I think a quorum favored documentation in the header itself, >> c.f. strbuf.h, string-list.h for the most desired state. (Although we do have >> Documentation/technical/api-string-list.txt as well ...) >> >> So maybe starting like this? > > That is very good. Let's drop that file from Documentation/technical > and do it like this (meaning, take both patches from you). > > Thanks. This patch is incorrect, as we need to do s/b -> -1/b -> -2/. (Wrong documentation is the worst) Also we'd probably want to see more of the functions documented. I'll see if I can extend this into a series documenting more functions. Thanks, Stefan ```