* [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).