{"thread":{"id":"52094","subject":"[PATCH 0/1] [Outreachy] documentation: remove empty doc files","startedAt":"2019-10-22T18:19:40Z","lastAt":"2019-10-24T20:48:47Z","messageCount":13,"participants":["Heba Waly via GitGitGadget","Emily Shaffer","Junio C Hamano","Heba Waly"],"isPatch":true,"patchVersion":1,"patchTotal":1},"messages":[{"id":"384616","messageId":"pull.412.git.1571768375.gitgitgadget@gmail.com","threadId":"52094","inReplyTo":null,"subject":"[PATCH 0/1] [Outreachy] documentation: remove empty doc files","fromName":"Heba Waly via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2019-10-22T18:19:34Z","receivedAt":"2019-10-22T18:19:40Z","isPatch":true,"sender":{"key":"heba.waly@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1539076?v=4"},"body":"Remove empty and redundant documentation files from the\nDocumentation/technical/ directory.\n\nAs part of moving the documentation from Documentation/technical/api-* to\nheader files, the following files are deleted because they include only TODO\nmessages with no documentation: Documentation/technical/api-grep.txt\nDocumentation/technical/api-object-access.txt\nDocumentation/technical/api-quote.txt\nDocumentation/technical/api-xdiff-interface.txt\n\nSigned-off-by: Heba Waly heba.waly@gmail.com [heba.waly@gmail.com]\n\nHeba Waly (1):\n documentation: remove empty doc files\n\n Documentation/technical/api-grep.txt | 8 --------\n Documentation/technical/api-object-access.txt | 15 ---------------\n Documentation/technical/api-quote.txt | 10 ----------\n Documentation/technical/api-xdiff-interface.txt | 7 -------\n 4 files changed, 40 deletions(-)\n delete mode 100644 Documentation/technical/api-grep.txt\n delete mode 100644 Documentation/technical/api-object-access.txt\n delete mode 100644 Documentation/technical/api-quote.txt\n delete mode 100644 Documentation/technical/api-xdiff-interface.txt\n\n\nbase-commit: d966095db01190a2196e31195ea6fa0c722aa732\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-412%2FHebaWaly%2Fdelete_empty_docs-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-412/HebaWaly/delete_empty_docs-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/412\n-- \ngitgitgadget\n"},{"id":"384617","messageId":"ffdde613d8ea2dc57719594aa0f89b6d6177b636.1571768375.git.gitgitgadget@gmail.com","threadId":"52094","inReplyTo":"pull.412.git.1571768375.gitgitgadget@gmail.com","subject":"[PATCH 1/1] documentation: remove empty doc files","fromName":"Heba Waly via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2019-10-22T18:19:35Z","receivedAt":"2019-10-22T18:19:42Z","isPatch":true,"sender":{"key":"heba.waly@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1539076?v=4"},"body":"From: Heba Waly \n\nRemove empty and redundant documentation files from the\nDocumentation/technical/ directory.\n\nAs part of moving the documentation from Documentation/technical/api-* to\nheader files, the following files are deleted because they include only\nTODO messages with no documentation to be moved:\nDocumentation/technical/api-grep.txt\nDocumentation/technical/api-object-access.txt\nDocumentation/technical/api-quote.txt\nDocumentation/technical/api-xdiff-interface.txt\n\nSigned-off-by: Heba Waly \n---\n Documentation/technical/api-grep.txt | 8 --------\n Documentation/technical/api-object-access.txt | 15 ---------------\n Documentation/technical/api-quote.txt | 10 ----------\n Documentation/technical/api-xdiff-interface.txt | 7 -------\n 4 files changed, 40 deletions(-)\n delete mode 100644 Documentation/technical/api-grep.txt\n delete mode 100644 Documentation/technical/api-object-access.txt\n delete mode 100644 Documentation/technical/api-quote.txt\n delete mode 100644 Documentation/technical/api-xdiff-interface.txt\n\ndiff --git a/Documentation/technical/api-grep.txt b/Documentation/technical/api-grep.txt\ndeleted file mode 100644\nindex a69cc8964d..0000000000\n--- a/Documentation/technical/api-grep.txt\n+++ /dev/null\n@@ -1,8 +0,0 @@\n-grep API\n-========\n-\n-Talk about , things like:\n-\n-* grep_buffer()\n-\n-(JC)\ndiff --git a/Documentation/technical/api-object-access.txt b/Documentation/technical/api-object-access.txt\ndeleted file mode 100644\nindex 5b29622d00..0000000000\n--- a/Documentation/technical/api-object-access.txt\n+++ /dev/null\n@@ -1,15 +0,0 @@\n-object access API\n-=================\n-\n-Talk about and family, things like\n-\n-* read_sha1_file()\n-* read_object_with_reference()\n-* has_sha1_file()\n-* write_sha1_file()\n-* pretend_object_file()\n-* lookup_{object,commit,tag,blob,tree}\n-* parse_{object,commit,tag,blob,tree}\n-* Use of object flags\n-\n-(JC, Shawn, Daniel, Dscho, Linus)\ndiff --git a/Documentation/technical/api-quote.txt b/Documentation/technical/api-quote.txt\ndeleted file mode 100644\nindex e8a1bce94e..0000000000\n--- a/Documentation/technical/api-quote.txt\n+++ /dev/null\n@@ -1,10 +0,0 @@\n-quote API\n-=========\n-\n-Talk about , things like\n-\n-* sq_quote and unquote\n-* c_style quote and unquote\n-* quoting for foreign languages\n-\n-(JC)\ndiff --git a/Documentation/technical/api-xdiff-interface.txt b/Documentation/technical/api-xdiff-interface.txt\ndeleted file mode 100644\nindex 6296ecad1d..0000000000\n--- a/Documentation/technical/api-xdiff-interface.txt\n+++ /dev/null\n@@ -1,7 +0,0 @@\n-xdiff interface API\n-===================\n-\n-Talk about our calling convention to xdiff library, including\n-xdiff_emit_consume_fn.\n-\n-(Dscho, JC)\n-- \ngitgitgadget\n"},{"id":"384630","messageId":"20191022210458.GE9323@google.com","threadId":"52094","inReplyTo":"ffdde613d8ea2dc57719594aa0f89b6d6177b636.1571768375.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 1/1] documentation: remove empty doc files","fromName":"Emily Shaffer","fromEmail":"emilyshaffer@google.com","sentAt":"2019-10-22T21:04:58Z","receivedAt":"2019-10-22T21:05:05Z","isPatch":true,"sender":{"key":"nasamuffin@google.com","avatar":"https://avatars.githubusercontent.com/u/1606826?v=4"},"body":"On Tue, Oct 22, 2019 at 06:19:35PM +0000, Heba Waly via GitGitGadget wrote:\n> From: Heba Waly \n> \n> Remove empty and redundant documentation files from the\n> Documentation/technical/ directory.\n> \n> As part of moving the documentation from Documentation/technical/api-* to\n> header files, the following files are deleted because they include only\n> TODO messages with no documentation to be moved:\n> Documentation/technical/api-grep.txt\n> Documentation/technical/api-object-access.txt\n> Documentation/technical/api-quote.txt\n> Documentation/technical/api-xdiff-interface.txt\n\nSame thing as I mentioned in your other review; what you've added to\nyour commit message now doesn't say anything you didn't say with the\ndiff. I can see that you removed empty documentation files; I can see\nthat those files include only TODO.\n\nMaybe you can explain why it's a bad developer experience to stumble\nacross these, and that those files sat untouched for years in the\nTODO(contributor-name) state.\n\n> \n> Signed-off-by: Heba Waly \n> ---\n> Documentation/technical/api-grep.txt | 8 --------\n> Documentation/technical/api-object-access.txt | 15 ---------------\n> Documentation/technical/api-quote.txt | 10 ----------\n> Documentation/technical/api-xdiff-interface.txt | 7 -------\n> 4 files changed, 40 deletions(-)\n> delete mode 100644 Documentation/technical/api-grep.txt\n> delete mode 100644 Documentation/technical/api-object-access.txt\n> delete mode 100644 Documentation/technical/api-quote.txt\n> delete mode 100644 Documentation/technical/api-xdiff-interface.txt\n\nAs for the content of this change, I absolutely approve. I've stumbled\nacross some of these empty docs while looking for answers before and\nfound it really demoralizing - the community is so interested in\nteaching me how to contribute that they've sat on a TODO for 12 years?\n:( I even held up api-grep.txt as a (bad) example in a talk I gave this\nyear. I'm happy to see these files go.\n\n - Emily\n"},{"id":"384649","messageId":"xmqqtv80jq3n.fsf@gitster-ct.c.googlers.com","threadId":"52094","inReplyTo":"20191022210458.GE9323@google.com","subject":"Re: [PATCH 1/1] documentation: remove empty doc files","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-10-22T23:51:56Z","receivedAt":"2019-10-22T23:52:01Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Emily Shaffer writes:\n\n> As for the content of this change, I absolutely approve. I've stumbled\n> across some of these empty docs while looking for answers before and\n> found it really demoralizing - the community is so interested in\n> teaching me how to contribute that they've sat on a TODO for 12 years?\n> :( I even held up api-grep.txt as a (bad) example in a talk I gave this\n> year. I'm happy to see these files go.\n\nI'd approve this move, too, especially if we accompanied deletion\nwith addition (or verification of existence) of necessary docs\nelsewhere (perhaps in *.h headers).\n\n"},{"id":"384679","messageId":"CACg5j24wn_rq5YgctLu-LAhXTk_pTkhmo6jkFL655dynN-zyLQ@mail.gmail.com","threadId":"52094","inReplyTo":"20191022210458.GE9323@google.com","subject":"Re: [PATCH 1/1] documentation: remove empty doc files","fromName":"Heba Waly","fromEmail":"heba.waly@gmail.com","sentAt":"2019-10-23T07:22:00Z","receivedAt":"2019-10-23T07:22:14Z","isPatch":true,"sender":{"key":"heba.waly@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1539076?v=4"},"body":"On Wed, Oct 23, 2019 at 10:05 AM Emily Shaffer wrote:\n>\n> On Tue, Oct 22, 2019 at 06:19:35PM +0000, Heba Waly via GitGitGadget wrote:\n> > From: Heba Waly \n> >\n> > Remove empty and redundant documentation files from the\n> > Documentation/technical/ directory.\n> >\n> > As part of moving the documentation from Documentation/technical/api-* to\n> > header files, the following files are deleted because they include only\n> > TODO messages with no documentation to be moved:\n> > Documentation/technical/api-grep.txt\n> > Documentation/technical/api-object-access.txt\n> > Documentation/technical/api-quote.txt\n> > Documentation/technical/api-xdiff-interface.txt\n>\n> Same thing as I mentioned in your other review; what you've added to\n> your commit message now doesn't say anything you didn't say with the\n> diff. I can see that you removed empty documentation files; I can see\n> that those files include only TODO.\n>\n> Maybe you can explain why it's a bad developer experience to stumble\n> across these, and that those files sat untouched for years in the\n> TODO(contributor-name) state.\nyou're right!\n> >\n> > Signed-off-by: Heba Waly \n> > ---\n> > Documentation/technical/api-grep.txt | 8 --------\n> > Documentation/technical/api-object-access.txt | 15 ---------------\n> > Documentation/technical/api-quote.txt | 10 ----------\n> > Documentation/technical/api-xdiff-interface.txt | 7 -------\n> > 4 files changed, 40 deletions(-)\n> > delete mode 100644 Documentation/technical/api-grep.txt\n> > delete mode 100644 Documentation/technical/api-object-access.txt\n> > delete mode 100644 Documentation/technical/api-quote.txt\n> > delete mode 100644 Documentation/technical/api-xdiff-interface.txt\n>\n> As for the content of this change, I absolutely approve. I've stumbled\n> across some of these empty docs while looking for answers before and\n> found it really demoralizing - the community is so interested in\n> teaching me how to contribute that they've sat on a TODO for 12 years?\n> :( I even held up api-grep.txt as a (bad) example in a talk I gave this\n> year. I'm happy to see these files go.\n>\n> - Emily\n"},{"id":"384681","messageId":"CACg5j25ANmBAUP8B+noRprqb3tgRanEyWQK8dx+QJGhKHZke6w@mail.gmail.com","threadId":"52094","inReplyTo":"xmqqtv80jq3n.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH 1/1] documentation: remove empty doc files","fromName":"Heba Waly","fromEmail":"heba.waly@gmail.com","sentAt":"2019-10-23T07:23:40Z","receivedAt":"2019-10-23T07:23:54Z","isPatch":true,"sender":{"key":"heba.waly@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1539076?v=4"},"body":"On Wed, Oct 23, 2019 at 12:52 PM Junio C Hamano wrote:\n>\n> Emily Shaffer writes:\n>\n> > As for the content of this change, I absolutely approve. I've stumbled\n> > across some of these empty docs while looking for answers before and\n> > found it really demoralizing - the community is so interested in\n> > teaching me how to contribute that they've sat on a TODO for 12 years?\n> > :( I even held up api-grep.txt as a (bad) example in a talk I gave this\n> > year. I'm happy to see these files go.\n>\n> I'd approve this move, too, especially if we accompanied deletion\n> with addition (or verification of existence) of necessary docs\n> elsewhere (perhaps in *.h headers).\nGood point, although not all corresponding header files are\ndocumented, but I'll include that in the commit message.\n\nThanks\n"},{"id":"384682","messageId":"pull.412.v2.git.1571815556.gitgitgadget@gmail.com","threadId":"52094","inReplyTo":"pull.412.git.1571768375.gitgitgadget@gmail.com","subject":"[PATCH v2 0/1] [Outreachy] documentation: remove empty doc files","fromName":"Heba Waly via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2019-10-23T07:25:55Z","receivedAt":"2019-10-23T07:26:00Z","isPatch":true,"sender":{"key":"heba.waly@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1539076?v=4"},"body":"Remove empty and redundant documentation files from the\nDocumentation/technical/ directory.\n\nThe empty doc files included only TODO messages with no documentation for\nyears. Instead an approach is being taken to keep all doc beside the code in\nthe relevant header files. Having empty doc files is confusing and\ndisappointing to anybody looking for information, besides having the\ndocumentation in header files makes it easier for developers to find the\ninformation they are looking for.\n\nhere's a list of the files removed and if the info can be found in the\ncorresponding header file: 1- Documentation/technical/api-grep.txt -> grep.h\ndoes not have enough documentation at the moment. 2-\nDocumentation/technical/api-object-access.txt -> sha1-file.c and object.h\nhave some details 3- Documentation/technical/api-quote.txt -> quote.h has\nsome details. 4- Documentation/technical/api-xdiff-interface.txt ->\nxdiff-interface.h has some details.\n\nSigned-off-by: Heba Waly heba.waly@gmail.com [heba.waly@gmail.com]\n\nHeba Waly (1):\n documentation: remove empty doc files\n\n Documentation/technical/api-grep.txt | 8 --------\n Documentation/technical/api-object-access.txt | 15 ---------------\n Documentation/technical/api-quote.txt | 10 ----------\n Documentation/technical/api-xdiff-interface.txt | 7 -------\n 4 files changed, 40 deletions(-)\n delete mode 100644 Documentation/technical/api-grep.txt\n delete mode 100644 Documentation/technical/api-object-access.txt\n delete mode 100644 Documentation/technical/api-quote.txt\n delete mode 100644 Documentation/technical/api-xdiff-interface.txt\n\n\nbase-commit: d966095db01190a2196e31195ea6fa0c722aa732\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-412%2FHebaWaly%2Fdelete_empty_docs-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-412/HebaWaly/delete_empty_docs-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/412\n\nRange-diff vs v1:\n\n 1: ffdde613d8 ! 1: 5cd79e24fe documentation: remove empty doc files\n @@ -5,13 +5,22 @@\n Remove empty and redundant documentation files from the\n Documentation/technical/ directory.\n \n - As part of moving the documentation from Documentation/technical/api-* to\n - header files, the following files are deleted because they include only\n - TODO messages with no documentation to be moved:\n - Documentation/technical/api-grep.txt\n - Documentation/technical/api-object-access.txt\n - Documentation/technical/api-quote.txt\n - Documentation/technical/api-xdiff-interface.txt\n + The empty doc files included only TODO messages with no documentation for\n + years. Instead an approach is being taken to keep all doc beside the code\n + in the relevant header files.\n + Having empty doc files is confusing and disappointing to anybody looking\n + for information, besides having the documentation in header files makes it\n + easier for developers to find the information they are looking for.\n +\n + here's a list of the files removed and if the info can be found in the\n + corresponding header file:\n + 1- Documentation/technical/api-grep.txt -> grep.h does not have enough\n + documentation at the moment.\n + 2- Documentation/technical/api-object-access.txt -> sha1-file.c and\n + object.h have some details\n + 3- Documentation/technical/api-quote.txt -> quote.h has some details.\n + 4- Documentation/technical/api-xdiff-interface.txt -> xdiff-interface.h has\n + some details.\n \n Signed-off-by: Heba Waly \n \n\n-- \ngitgitgadget\n"},{"id":"384683","messageId":"5cd79e24fe6bde7c5d10e1c2cae660858e3c4051.1571815556.git.gitgitgadget@gmail.com","threadId":"52094","inReplyTo":"pull.412.v2.git.1571815556.gitgitgadget@gmail.com","subject":"[PATCH v2 1/1] documentation: remove empty doc files","fromName":"Heba Waly via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2019-10-23T07:25:56Z","receivedAt":"2019-10-23T07:26:01Z","isPatch":true,"sender":{"key":"heba.waly@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1539076?v=4"},"body":"From: Heba Waly \n\nRemove empty and redundant documentation files from the\nDocumentation/technical/ directory.\n\nThe empty doc files included only TODO messages with no documentation for\nyears. Instead an approach is being taken to keep all doc beside the code\nin the relevant header files.\nHaving empty doc files is confusing and disappointing to anybody looking\nfor information, besides having the documentation in header files makes it\neasier for developers to find the information they are looking for.\n\nhere's a list of the files removed and if the info can be found in the\ncorresponding header file:\n1- Documentation/technical/api-grep.txt -> grep.h does not have enough\ndocumentation at the moment.\n2- Documentation/technical/api-object-access.txt -> sha1-file.c and\nobject.h have some details\n3- Documentation/technical/api-quote.txt -> quote.h has some details.\n4- Documentation/technical/api-xdiff-interface.txt -> xdiff-interface.h has\nsome details.\n\nSigned-off-by: Heba Waly \n---\n Documentation/technical/api-grep.txt | 8 --------\n Documentation/technical/api-object-access.txt | 15 ---------------\n Documentation/technical/api-quote.txt | 10 ----------\n Documentation/technical/api-xdiff-interface.txt | 7 -------\n 4 files changed, 40 deletions(-)\n delete mode 100644 Documentation/technical/api-grep.txt\n delete mode 100644 Documentation/technical/api-object-access.txt\n delete mode 100644 Documentation/technical/api-quote.txt\n delete mode 100644 Documentation/technical/api-xdiff-interface.txt\n\ndiff --git a/Documentation/technical/api-grep.txt b/Documentation/technical/api-grep.txt\ndeleted file mode 100644\nindex a69cc8964d..0000000000\n--- a/Documentation/technical/api-grep.txt\n+++ /dev/null\n@@ -1,8 +0,0 @@\n-grep API\n-========\n-\n-Talk about , things like:\n-\n-* grep_buffer()\n-\n-(JC)\ndiff --git a/Documentation/technical/api-object-access.txt b/Documentation/technical/api-object-access.txt\ndeleted file mode 100644\nindex 5b29622d00..0000000000\n--- a/Documentation/technical/api-object-access.txt\n+++ /dev/null\n@@ -1,15 +0,0 @@\n-object access API\n-=================\n-\n-Talk about and family, things like\n-\n-* read_sha1_file()\n-* read_object_with_reference()\n-* has_sha1_file()\n-* write_sha1_file()\n-* pretend_object_file()\n-* lookup_{object,commit,tag,blob,tree}\n-* parse_{object,commit,tag,blob,tree}\n-* Use of object flags\n-\n-(JC, Shawn, Daniel, Dscho, Linus)\ndiff --git a/Documentation/technical/api-quote.txt b/Documentation/technical/api-quote.txt\ndeleted file mode 100644\nindex e8a1bce94e..0000000000\n--- a/Documentation/technical/api-quote.txt\n+++ /dev/null\n@@ -1,10 +0,0 @@\n-quote API\n-=========\n-\n-Talk about , things like\n-\n-* sq_quote and unquote\n-* c_style quote and unquote\n-* quoting for foreign languages\n-\n-(JC)\ndiff --git a/Documentation/technical/api-xdiff-interface.txt b/Documentation/technical/api-xdiff-interface.txt\ndeleted file mode 100644\nindex 6296ecad1d..0000000000\n--- a/Documentation/technical/api-xdiff-interface.txt\n+++ /dev/null\n@@ -1,7 +0,0 @@\n-xdiff interface API\n-===================\n-\n-Talk about our calling convention to xdiff library, including\n-xdiff_emit_consume_fn.\n-\n-(Dscho, JC)\n-- \ngitgitgadget\n"},{"id":"384725","messageId":"20191023214404.GB124161@google.com","threadId":"52094","inReplyTo":"5cd79e24fe6bde7c5d10e1c2cae660858e3c4051.1571815556.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 1/1] documentation: remove empty doc files","fromName":"Emily Shaffer","fromEmail":"emilyshaffer@google.com","sentAt":"2019-10-23T21:44:04Z","receivedAt":"2019-10-23T21:44:11Z","isPatch":true,"sender":{"key":"nasamuffin@google.com","avatar":"https://avatars.githubusercontent.com/u/1606826?v=4"},"body":"On Wed, Oct 23, 2019 at 07:25:56AM +0000, Heba Waly via GitGitGadget wrote:\n> From: Heba Waly \n> \n> Remove empty and redundant documentation files from the\n> Documentation/technical/ directory.\n> \n> The empty doc files included only TODO messages with no documentation for\n> years. Instead an approach is being taken to keep all doc beside the code\n> in the relevant header files.\n> Having empty doc files is confusing and disappointing to anybody looking\n> for information, besides having the documentation in header files makes it\n> easier for developers to find the information they are looking for.\n> \n> here's a list of the files removed and if the info can be found in the\n> corresponding header file:\nI think you can remove the above; in lots of composition contexts it\ntends to be bad form to say \"Here is : \" - don't\nwarn us that you're going to present it, just present it. :) (Or, at\nleast, this has been drilled into my head by many high school English\nteachers...)\n\nMaybe you could say something like, \"Some of the content which could\nhave gone here already exists elsewhere:\" If you take that suggestion,\nyou can probably move grep.h to the bottom, as it's the exception which\ndoesn't have content that exists elsewhere.\n\n> 1- Documentation/technical/api-grep.txt -> grep.h does not have enough\n> documentation at the moment.\n> 2- Documentation/technical/api-object-access.txt -> sha1-file.c and\n> object.h have some details\n> 3- Documentation/technical/api-quote.txt -> quote.h has some details.\n> 4- Documentation/technical/api-xdiff-interface.txt -> xdiff-interface.h has\n> some details.\n\nFor this list, I think you can remove the numbered bullet, and the\nleading \"Documentation/technical/\" - we can see the files deleted from\nthe diff.\n\n - Emily\n"},{"id":"384759","messageId":"CACg5j27yUxR9aPWH8-ji==wx6GcNcEGYQwK3wn+T6-UtLkJqpA@mail.gmail.com","threadId":"52094","inReplyTo":"20191023214404.GB124161@google.com","subject":"Re: [PATCH v2 1/1] documentation: remove empty doc files","fromName":"Heba Waly","fromEmail":"heba.waly@gmail.com","sentAt":"2019-10-24T10:43:15Z","receivedAt":"2019-10-24T10:43:30Z","isPatch":true,"sender":{"key":"heba.waly@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1539076?v=4"},"body":"On Thu, Oct 24, 2019 at 10:44 AM Emily Shaffer wrote:\n>\n> On Wed, Oct 23, 2019 at 07:25:56AM +0000, Heba Waly via GitGitGadget wrote:\n> > From: Heba Waly \n> >\n> > Remove empty and redundant documentation files from the\n> > Documentation/technical/ directory.\n> >\n> > The empty doc files included only TODO messages with no documentation for\n> > years. Instead an approach is being taken to keep all doc beside the code\n> > in the relevant header files.\n> > Having empty doc files is confusing and disappointing to anybody looking\n> > for information, besides having the documentation in header files makes it\n> > easier for developers to find the information they are looking for.\n> >\n> > here's a list of the files removed and if the info can be found in the\n> > corresponding header file:\n> I think you can remove the above; in lots of composition contexts it\n> tends to be bad form to say \"Here is : \" - don't\n> warn us that you're going to present it, just present it. :) (Or, at\n> least, this has been drilled into my head by many high school English\n> teachers...)\n>\n> Maybe you could say something like, \"Some of the content which could\n> have gone here already exists elsewhere:\" If you take that suggestion,\n> you can probably move grep.h to the bottom, as it's the exception which\n> doesn't have content that exists elsewhere.\nThat sounds better. Okay.\n> > 1- Documentation/technical/api-grep.txt -> grep.h does not have enough\n> > documentation at the moment.\n> > 2- Documentation/technical/api-object-access.txt -> sha1-file.c and\n> > object.h have some details\n> > 3- Documentation/technical/api-quote.txt -> quote.h has some details.\n> > 4- Documentation/technical/api-xdiff-interface.txt -> xdiff-interface.h has\n> > some details.\n>\n> For this list, I think you can remove the numbered bullet, and the\n> leading \"Documentation/technical/\" - we can see the files deleted from\n> the diff.\nyes.\n\n> - Emily\n\nThanks\n"},{"id":"384761","messageId":"pull.412.v3.git.1571916551.gitgitgadget@gmail.com","threadId":"52094","inReplyTo":"pull.412.v2.git.1571815556.gitgitgadget@gmail.com","subject":"[PATCH v3 0/1] [Outreachy] documentation: remove empty doc files","fromName":"Heba Waly via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2019-10-24T11:29:10Z","receivedAt":"2019-10-24T11:29:16Z","isPatch":true,"sender":{"key":"heba.waly@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1539076?v=4"},"body":"Remove empty and redundant documentation files from the\nDocumentation/technical/ directory.\n\nThe empty doc files included only TODO messages with no documentation for\nyears. Instead an approach is being taken to keep all doc beside the code in\nthe relevant header files. Having empty doc files is confusing and\ndisappointing to anybody looking for information, besides having the\ndocumentation in header files makes it easier for developers to find the\ninformation they are looking for.\n\nSome of the content which could have gone here already exists elsewhere:\n\n * api-object-access.txt -> sha1-file.c and object.h have some details.\n * api-quote.txt -> quote.h has some details.\n * api-xdiff-interface.txt -> xdiff-interface.h has some details.\n * api-grep.txt -> grep.h does not have enough documentation at the moment.\n\nSigned-off-by: Heba Waly heba.waly@gmail.com [heba.waly@gmail.com]\n\nHeba Waly (1):\n documentation: remove empty doc files\n\n Documentation/technical/api-grep.txt | 8 --------\n Documentation/technical/api-object-access.txt | 15 ---------------\n Documentation/technical/api-quote.txt | 10 ----------\n Documentation/technical/api-xdiff-interface.txt | 7 -------\n 4 files changed, 40 deletions(-)\n delete mode 100644 Documentation/technical/api-grep.txt\n delete mode 100644 Documentation/technical/api-object-access.txt\n delete mode 100644 Documentation/technical/api-quote.txt\n delete mode 100644 Documentation/technical/api-xdiff-interface.txt\n\n\nbase-commit: d966095db01190a2196e31195ea6fa0c722aa732\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-412%2FHebaWaly%2Fdelete_empty_docs-v3\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-412/HebaWaly/delete_empty_docs-v3\nPull-Request: https://github.com/gitgitgadget/git/pull/412\n\nRange-diff vs v2:\n\n 1: 5cd79e24fe ! 1: ee64a075d3 documentation: remove empty doc files\n @@ -12,15 +12,11 @@\n for information, besides having the documentation in header files makes it\n easier for developers to find the information they are looking for.\n \n - here's a list of the files removed and if the info can be found in the\n - corresponding header file:\n - 1- Documentation/technical/api-grep.txt -> grep.h does not have enough\n - documentation at the moment.\n - 2- Documentation/technical/api-object-access.txt -> sha1-file.c and\n - object.h have some details\n - 3- Documentation/technical/api-quote.txt -> quote.h has some details.\n - 4- Documentation/technical/api-xdiff-interface.txt -> xdiff-interface.h has\n - some details.\n + Some of the content which could have gone here already exists elsewhere:\n + - api-object-access.txt -> sha1-file.c and object.h have some details.\n + - api-quote.txt -> quote.h has some details.\n + - api-xdiff-interface.txt -> xdiff-interface.h has some details.\n + - api-grep.txt -> grep.h does not have enough documentation at the moment.\n \n Signed-off-by: Heba Waly \n \n\n-- \ngitgitgadget\n"},{"id":"384762","messageId":"ee64a075d3074718a47da4ed369cee6923d0b460.1571916551.git.gitgitgadget@gmail.com","threadId":"52094","inReplyTo":"pull.412.v3.git.1571916551.gitgitgadget@gmail.com","subject":"[PATCH v3 1/1] documentation: remove empty doc files","fromName":"Heba Waly via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2019-10-24T11:29:11Z","receivedAt":"2019-10-24T11:29:18Z","isPatch":true,"sender":{"key":"heba.waly@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1539076?v=4"},"body":"From: Heba Waly \n\nRemove empty and redundant documentation files from the\nDocumentation/technical/ directory.\n\nThe empty doc files included only TODO messages with no documentation for\nyears. Instead an approach is being taken to keep all doc beside the code\nin the relevant header files.\nHaving empty doc files is confusing and disappointing to anybody looking\nfor information, besides having the documentation in header files makes it\neasier for developers to find the information they are looking for.\n\nSome of the content which could have gone here already exists elsewhere:\n- api-object-access.txt -> sha1-file.c and object.h have some details.\n- api-quote.txt -> quote.h has some details.\n- api-xdiff-interface.txt -> xdiff-interface.h has some details.\n- api-grep.txt -> grep.h does not have enough documentation at the moment.\n\nSigned-off-by: Heba Waly \n---\n Documentation/technical/api-grep.txt | 8 --------\n Documentation/technical/api-object-access.txt | 15 ---------------\n Documentation/technical/api-quote.txt | 10 ----------\n Documentation/technical/api-xdiff-interface.txt | 7 -------\n 4 files changed, 40 deletions(-)\n delete mode 100644 Documentation/technical/api-grep.txt\n delete mode 100644 Documentation/technical/api-object-access.txt\n delete mode 100644 Documentation/technical/api-quote.txt\n delete mode 100644 Documentation/technical/api-xdiff-interface.txt\n\ndiff --git a/Documentation/technical/api-grep.txt b/Documentation/technical/api-grep.txt\ndeleted file mode 100644\nindex a69cc8964d..0000000000\n--- a/Documentation/technical/api-grep.txt\n+++ /dev/null\n@@ -1,8 +0,0 @@\n-grep API\n-========\n-\n-Talk about , things like:\n-\n-* grep_buffer()\n-\n-(JC)\ndiff --git a/Documentation/technical/api-object-access.txt b/Documentation/technical/api-object-access.txt\ndeleted file mode 100644\nindex 5b29622d00..0000000000\n--- a/Documentation/technical/api-object-access.txt\n+++ /dev/null\n@@ -1,15 +0,0 @@\n-object access API\n-=================\n-\n-Talk about and family, things like\n-\n-* read_sha1_file()\n-* read_object_with_reference()\n-* has_sha1_file()\n-* write_sha1_file()\n-* pretend_object_file()\n-* lookup_{object,commit,tag,blob,tree}\n-* parse_{object,commit,tag,blob,tree}\n-* Use of object flags\n-\n-(JC, Shawn, Daniel, Dscho, Linus)\ndiff --git a/Documentation/technical/api-quote.txt b/Documentation/technical/api-quote.txt\ndeleted file mode 100644\nindex e8a1bce94e..0000000000\n--- a/Documentation/technical/api-quote.txt\n+++ /dev/null\n@@ -1,10 +0,0 @@\n-quote API\n-=========\n-\n-Talk about , things like\n-\n-* sq_quote and unquote\n-* c_style quote and unquote\n-* quoting for foreign languages\n-\n-(JC)\ndiff --git a/Documentation/technical/api-xdiff-interface.txt b/Documentation/technical/api-xdiff-interface.txt\ndeleted file mode 100644\nindex 6296ecad1d..0000000000\n--- a/Documentation/technical/api-xdiff-interface.txt\n+++ /dev/null\n@@ -1,7 +0,0 @@\n-xdiff interface API\n-===================\n-\n-Talk about our calling convention to xdiff library, including\n-xdiff_emit_consume_fn.\n-\n-(Dscho, JC)\n-- \ngitgitgadget\n"},{"id":"384792","messageId":"20191024204840.GH9323@google.com","threadId":"52094","inReplyTo":"ee64a075d3074718a47da4ed369cee6923d0b460.1571916551.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v3 1/1] documentation: remove empty doc files","fromName":"Emily Shaffer","fromEmail":"emilyshaffer@google.com","sentAt":"2019-10-24T20:48:40Z","receivedAt":"2019-10-24T20:48:47Z","isPatch":true,"sender":{"key":"nasamuffin@google.com","avatar":"https://avatars.githubusercontent.com/u/1606826?v=4"},"body":"On Thu, Oct 24, 2019 at 11:29:11AM +0000, Heba Waly via GitGitGadget wrote:\n> From: Heba Waly \n> \n> Remove empty and redundant documentation files from the\n> Documentation/technical/ directory.\n> \n> The empty doc files included only TODO messages with no documentation for\n> years. Instead an approach is being taken to keep all doc beside the code\n> in the relevant header files.\n> Having empty doc files is confusing and disappointing to anybody looking\n> for information, besides having the documentation in header files makes it\n> easier for developers to find the information they are looking for.\n> \n> Some of the content which could have gone here already exists elsewhere:\n> - api-object-access.txt -> sha1-file.c and object.h have some details.\n> - api-quote.txt -> quote.h has some details.\n> - api-xdiff-interface.txt -> xdiff-interface.h has some details.\n> - api-grep.txt -> grep.h does not have enough documentation at the moment.\n> \n> Signed-off-by: Heba Waly \n\nReviewed-by: Emily Shaffer \n\nThanks, Heba.\n - Emily\n"}]}