{"thread":{"id":"46798","subject":"[PATCH 0/2] Two small comment fixes.","startedAt":"2017-09-21T12:44:22Z","lastAt":"2017-09-21T17:53:04Z","messageCount":5,"participants":["Han-Wen Nienhuys","Jeff King","Brandon Williams"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"328565","messageId":"20170921124338.26626-1-hanwen@google.com","threadId":"46798","inReplyTo":null,"subject":"[PATCH 0/2] Two small comment fixes.","fromName":"Han-Wen Nienhuys","fromEmail":"hanwen@google.com","sentAt":"2017-09-21T12:43:36Z","receivedAt":"2017-09-21T12:44:22Z","isPatch":true,"sender":{"key":"hanwen@google.com","avatar":"https://avatars.githubusercontent.com/u/31547?v=4"},"body":"Han-Wen Nienhuys (2):\n Fix typo in submodule.h\n Document the string_list structure\n\n string-list.h | 6 ++++++\n submodule.h | 2 +-\n 2 files changed, 7 insertions(+), 1 deletion(-)\n\n--\n2.14.1.821.g8fa685d3b7-goog\n"},{"id":"328566","messageId":"20170921124338.26626-2-hanwen@google.com","threadId":"46798","inReplyTo":"20170921124338.26626-1-hanwen@google.com","subject":"[PATCH 1/2] Fix typo in submodule.h","fromName":"Han-Wen Nienhuys","fromEmail":"hanwen@google.com","sentAt":"2017-09-21T12:43:37Z","receivedAt":"2017-09-21T12:44:27Z","isPatch":true,"sender":{"key":"hanwen@google.com","avatar":"https://avatars.githubusercontent.com/u/31547?v=4"},"body":"Signed-off-by: Han-Wen Nienhuys \n---\n submodule.h | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/submodule.h b/submodule.h\nindex 6b52133c8..f0da0277a 100644\n--- a/submodule.h\n+++ b/submodule.h\n@@ -120,7 +120,7 @@ extern int submodule_move_head(const char *path,\n \n /*\n * Prepare the \"env_array\" parameter of a \"struct child_process\" for executing\n- * a submodule by clearing any repo-specific envirionment variables, but\n+ * a submodule by clearing any repo-specific environment variables, but\n * retaining any config in the environment.\n */\n extern void prepare_submodule_repo_env(struct argv_array *out);\n-- \n2.14.1.821.g8fa685d3b7-goog\n\n"},{"id":"328567","messageId":"20170921124338.26626-3-hanwen@google.com","threadId":"46798","inReplyTo":"20170921124338.26626-1-hanwen@google.com","subject":"[PATCH 2/2] Document the string_list structure","fromName":"Han-Wen Nienhuys","fromEmail":"hanwen@google.com","sentAt":"2017-09-21T12:43:38Z","receivedAt":"2017-09-21T12:44:28Z","isPatch":true,"sender":{"key":"hanwen@google.com","avatar":"https://avatars.githubusercontent.com/u/31547?v=4"},"body":"Signed-off-by: Han-Wen Nienhuys \n---\n string-list.h | 6 ++++++\n 1 file changed, 6 insertions(+)\n\ndiff --git a/string-list.h b/string-list.h\nindex 29bfb7ae4..08b534166 100644\n--- a/string-list.h\n+++ b/string-list.h\n@@ -8,6 +8,12 @@ struct string_list_item {\n \n typedef int (*compare_strings_fn)(const char *, const char *);\n \n+/* A resizable array of strings. The strings are owned if\n+ * 'strdup_strings' is set. It can be used as a sorted array, and a\n+ * custom comparison may be given in 'cmp'. The field 'items[i].util'\n+ * may be used to implement an array of pairs. In that case, the\n+ * caller is responsible for managing memory pointed to by 'util'.\n+ */\n struct string_list {\n \tstruct string_list_item *items;\n \tunsigned int nr, alloc;\n-- \n2.14.1.821.g8fa685d3b7-goog\n\n"},{"id":"328573","messageId":"20170921162414.h3lapq6ahdbamlu6@sigill.intra.peff.net","threadId":"46798","inReplyTo":"20170921124338.26626-3-hanwen@google.com","subject":"Re: [PATCH 2/2] Document the string_list structure","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-09-21T16:24:15Z","receivedAt":"2017-09-21T16:24:24Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Sep 21, 2017 at 02:43:38PM +0200, Han-Wen Nienhuys wrote:\n\n> Signed-off-by: Han-Wen Nienhuys \n> ---\n> string-list.h | 6 ++++++\n> 1 file changed, 6 insertions(+)\n> \n> diff --git a/string-list.h b/string-list.h\n> index 29bfb7ae4..08b534166 100644\n> --- a/string-list.h\n> +++ b/string-list.h\n> @@ -8,6 +8,12 @@ struct string_list_item {\n> \n> typedef int (*compare_strings_fn)(const char *, const char *);\n> \n> +/* A resizable array of strings. The strings are owned if\n> + * 'strdup_strings' is set. It can be used as a sorted array, and a\n> + * custom comparison may be given in 'cmp'. The field 'items[i].util'\n> + * may be used to implement an array of pairs. In that case, the\n> + * caller is responsible for managing memory pointed to by 'util'.\n> + */\n> struct string_list {\n> \tstruct string_list_item *items;\n> \tunsigned int nr, alloc;\n\nThere's a considerable amount of documentation for string-list in\nDocumentation/technical/api-string-list.txt.\n\nPerhaps we should look at migrating it into string-list.h, where it's\nmore likely to be found (and kept up to date). We did something similar\nfor strbuf.h a while back, and I think the result is much better. See\nthe commits in:\n\n git log bdfdaa4978^..d468fa2721\n\nfor an example.\n\n-Peff\n"},{"id":"328580","messageId":"20170921175257.GA72184@google.com","threadId":"46798","inReplyTo":"20170921124338.26626-3-hanwen@google.com","subject":"Re: [PATCH 2/2] Document the string_list structure","fromName":"Brandon Williams","fromEmail":"bmwill@google.com","sentAt":"2017-09-21T17:52:57Z","receivedAt":"2017-09-21T17:53:04Z","isPatch":true,"sender":{"key":"bwilliams.eng@gmail.com","avatar":null},"body":"On 09/21, Han-Wen Nienhuys wrote:\n> Signed-off-by: Han-Wen Nienhuys \n> ---\n> string-list.h | 6 ++++++\n> 1 file changed, 6 insertions(+)\n> \n> diff --git a/string-list.h b/string-list.h\n> index 29bfb7ae4..08b534166 100644\n> --- a/string-list.h\n> +++ b/string-list.h\n> @@ -8,6 +8,12 @@ struct string_list_item {\n> \n> typedef int (*compare_strings_fn)(const char *, const char *);\n> \n> +/* A resizable array of strings. The strings are owned if\n\nnit: the start of the comment block should be on its own line:\n\n /*\n * A resizable ...\n\n> + * 'strdup_strings' is set. It can be used as a sorted array, and a\n> + * custom comparison may be given in 'cmp'. The field 'items[i].util'\n> + * may be used to implement an array of pairs. In that case, the\n> + * caller is responsible for managing memory pointed to by 'util'.\n> + */\n\nThe util field can be freed if 'free_util' is set when calling\nstring_list_clear() but yeah, in general the caller is managing that\nmemory especially if a complex free function is required (in the case of\nallocating a struct with dynamically allocated fields to be stored in\nthe util feild).\n\nJust pointing that out, and I'm happy with this and the previous patch.\n\n> struct string_list {\n> \tstruct string_list_item *items;\n> \tunsigned int nr, alloc;\n> -- \n> 2.14.1.821.g8fa685d3b7-goog\n> \n\n\n\n-- \nBrandon Williams\n"}]}