* [PATCH] documentation: remove unfinished documentation @ 2017-01-17 20:01 Stefan Beller 2017-01-17 20:36 ` Junio C Hamano 0 siblings, 1 reply; 5+ messages in thread From: Stefan Beller @ 2017-01-17 20:01 UTC (permalink / raw) To: gitster; +Cc: git, Stefan Beller 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 <sbeller@google.com> --- 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 <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.297.g298debce27 ^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH] documentation: remove unfinished documentation 2017-01-17 20:01 [PATCH] documentation: remove unfinished documentation Stefan Beller @ 2017-01-17 20:36 ` Junio C Hamano 2017-01-17 20:46 ` [PATCH] document index_name_pos Stefan Beller 0 siblings, 1 reply; 5+ messages in thread From: Junio C Hamano @ 2017-01-17 20:36 UTC (permalink / raw) To: Stefan Beller; +Cc: git Stefan Beller <sbeller@google.com> 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 <sbeller@google.com> > --- > > 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. ^ permalink raw reply [flat|nested] 5+ messages in thread
* [PATCH] document index_name_pos 2017-01-17 20:36 ` Junio C Hamano @ 2017-01-17 20:46 ` Stefan Beller 2017-01-17 21:43 ` Junio C Hamano 0 siblings, 1 reply; 5+ messages in thread From: Stefan Beller @ 2017-01-17 20:46 UTC (permalink / raw) To: gitster; +Cc: git, Stefan Beller Signed-off-by: Stefan Beller <sbeller@google.com> --- > 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 ^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH] document index_name_pos 2017-01-17 20:46 ` [PATCH] document index_name_pos Stefan Beller @ 2017-01-17 21:43 ` Junio C Hamano 2017-01-17 21:47 ` Stefan Beller 0 siblings, 1 reply; 5+ messages in thread From: Junio C Hamano @ 2017-01-17 21:43 UTC (permalink / raw) To: Stefan Beller; +Cc: git Stefan Beller <sbeller@google.com> writes: > Signed-off-by: Stefan Beller <sbeller@google.com> > --- > >> 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 */ ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] document index_name_pos 2017-01-17 21:43 ` Junio C Hamano @ 2017-01-17 21:47 ` Stefan Beller 0 siblings, 0 replies; 5+ messages in thread From: Stefan Beller @ 2017-01-17 21:47 UTC (permalink / raw) To: Junio C Hamano; +Cc: git@vger.kernel.org On Tue, Jan 17, 2017 at 1:43 PM, Junio C Hamano <gitster@pobox.com> wrote: > Stefan Beller <sbeller@google.com> writes: > >> Signed-off-by: Stefan Beller <sbeller@google.com> >> --- >> >>> 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2017-01-17 21:47 UTC | newest] Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2017-01-17 20:01 [PATCH] documentation: remove unfinished documentation Stefan Beller 2017-01-17 20:36 ` Junio C Hamano 2017-01-17 20:46 ` [PATCH] document index_name_pos Stefan Beller 2017-01-17 21:43 ` Junio C Hamano 2017-01-17 21:47 ` Stefan Beller
Code repositories for project(s) associated with this public inbox https://80x24.org/mirrors/git.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).