threads / patch / 44899

patchdocumentation: remove unfinished documentation

Subject: [PATCH] documentation: remove unfinished documentation

## tl;dr

5 messages between Jan 17, 2017 and Jan 17, 2017. Diffs are folded; open one to read it.

replies: 4people: 2as markdown or json

Stefan Beller· Jan 17, 2017, 20:01 UTC · lore

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
Show changes to Documentation/technical/api-in-core-index.txt +0 −21
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
Junio C Hamano· Jan 17, 2017, 20:36 UTC · re: Stefan Beller · lore

Re: [PATCH] documentation: remove unfinished documentation

Stefan Beller <sbeller@google.com> writes:
Show 14 quoted lines
> 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.

Stefan Beller· Jan 17, 2017, 20:46 UTC · re: Junio C Hamano · lore

[PATCH] document index_name_pos

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(+)
Show changes to cache.h +13 −0
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· Jan 17, 2017, 21:43 UTC · re: Stefan Beller · lore

Re: [PATCH] document index_name_pos

Stefan Beller <sbeller@google.com> writes:
Show 14 quoted lines
> 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.
Show 32 quoted lines
>
> 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· Jan 17, 2017, 21:47 UTC · re: Junio C Hamano · lore

Re: [PATCH] document index_name_pos

On Tue, Jan 17, 2017 at 1:43 PM, Junio C Hamano <gitster@pobox.com> wrote:
Show 21 quoted lines
> 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

← back to recent threads