| Message ID | ffdde613d8ea2dc57719594aa0f89b6d6177b636.1571768375.git.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | documentation: remove empty doc files | expand |
On Tue, Oct 22, 2019 at 06:19:35PM +0000, Heba Waly via GitGitGadget wrote: > From: Heba Waly <heba.waly@gmail.com> > > Remove empty and redundant documentation files from the > Documentation/technical/ directory. > > As part of moving the documentation from Documentation/technical/api-* to > header files, the following files are deleted because they include only > TODO messages with no documentation to be moved: > Documentation/technical/api-grep.txt > Documentation/technical/api-object-access.txt > Documentation/technical/api-quote.txt > Documentation/technical/api-xdiff-interface.txt Same thing as I mentioned in your other review; what you've added to your commit message now doesn't say anything you didn't say with the diff. I can see that you removed empty documentation files; I can see that those files include only TODO. Maybe you can explain why it's a bad developer experience to stumble across these, and that those files sat untouched for years in the TODO(contributor-name) state. > > Signed-off-by: Heba Waly <heba.waly@gmail.com> > --- > Documentation/technical/api-grep.txt | 8 -------- > Documentation/technical/api-object-access.txt | 15 --------------- > Documentation/technical/api-quote.txt | 10 ---------- > Documentation/technical/api-xdiff-interface.txt | 7 ------- > 4 files changed, 40 deletions(-) > delete mode 100644 Documentation/technical/api-grep.txt > delete mode 100644 Documentation/technical/api-object-access.txt > delete mode 100644 Documentation/technical/api-quote.txt > delete mode 100644 Documentation/technical/api-xdiff-interface.txt As for the content of this change, I absolutely approve. I've stumbled across some of these empty docs while looking for answers before and found it really demoralizing - the community is so interested in teaching me how to contribute that they've sat on a TODO for 12 years? :( I even held up api-grep.txt as a (bad) example in a talk I gave this year. I'm happy to see these files go. - Emily
Emily Shaffer <emilyshaffer@google.com> writes: > As for the content of this change, I absolutely approve. I've stumbled > across some of these empty docs while looking for answers before and > found it really demoralizing - the community is so interested in > teaching me how to contribute that they've sat on a TODO for 12 years? > :( I even held up api-grep.txt as a (bad) example in a talk I gave this > year. I'm happy to see these files go. I'd approve this move, too, especially if we accompanied deletion with addition (or verification of existence) of necessary docs elsewhere (perhaps in *.h headers).
On Wed, Oct 23, 2019 at 10:05 AM Emily Shaffer <emilyshaffer@google.com> wrote: > > On Tue, Oct 22, 2019 at 06:19:35PM +0000, Heba Waly via GitGitGadget wrote: > > From: Heba Waly <heba.waly@gmail.com> > > > > Remove empty and redundant documentation files from the > > Documentation/technical/ directory. > > > > As part of moving the documentation from Documentation/technical/api-* to > > header files, the following files are deleted because they include only > > TODO messages with no documentation to be moved: > > Documentation/technical/api-grep.txt > > Documentation/technical/api-object-access.txt > > Documentation/technical/api-quote.txt > > Documentation/technical/api-xdiff-interface.txt > > Same thing as I mentioned in your other review; what you've added to > your commit message now doesn't say anything you didn't say with the > diff. I can see that you removed empty documentation files; I can see > that those files include only TODO. > > Maybe you can explain why it's a bad developer experience to stumble > across these, and that those files sat untouched for years in the > TODO(contributor-name) state. you're right! > > > > Signed-off-by: Heba Waly <heba.waly@gmail.com> > > --- > > Documentation/technical/api-grep.txt | 8 -------- > > Documentation/technical/api-object-access.txt | 15 --------------- > > Documentation/technical/api-quote.txt | 10 ---------- > > Documentation/technical/api-xdiff-interface.txt | 7 ------- > > 4 files changed, 40 deletions(-) > > delete mode 100644 Documentation/technical/api-grep.txt > > delete mode 100644 Documentation/technical/api-object-access.txt > > delete mode 100644 Documentation/technical/api-quote.txt > > delete mode 100644 Documentation/technical/api-xdiff-interface.txt > > As for the content of this change, I absolutely approve. I've stumbled > across some of these empty docs while looking for answers before and > found it really demoralizing - the community is so interested in > teaching me how to contribute that they've sat on a TODO for 12 years? > :( I even held up api-grep.txt as a (bad) example in a talk I gave this > year. I'm happy to see these files go. > > - Emily
On Wed, Oct 23, 2019 at 12:52 PM Junio C Hamano <gitster@pobox.com> wrote: > > Emily Shaffer <emilyshaffer@google.com> writes: > > > As for the content of this change, I absolutely approve. I've stumbled > > across some of these empty docs while looking for answers before and > > found it really demoralizing - the community is so interested in > > teaching me how to contribute that they've sat on a TODO for 12 years? > > :( I even held up api-grep.txt as a (bad) example in a talk I gave this > > year. I'm happy to see these files go. > > I'd approve this move, too, especially if we accompanied deletion > with addition (or verification of existence) of necessary docs > elsewhere (perhaps in *.h headers). Good point, although not all corresponding header files are documented, but I'll include that in the commit message. Thanks
diff --git a/Documentation/technical/api-grep.txt b/Documentation/technical/api-grep.txt deleted file mode 100644 index a69cc8964d..0000000000 --- a/Documentation/technical/api-grep.txt +++ /dev/null @@ -1,8 +0,0 @@ -grep API -======== - -Talk about <grep.h>, things like: - -* grep_buffer() - -(JC) diff --git a/Documentation/technical/api-object-access.txt b/Documentation/technical/api-object-access.txt deleted file mode 100644 index 5b29622d00..0000000000 --- a/Documentation/technical/api-object-access.txt +++ /dev/null @@ -1,15 +0,0 @@ -object access API -================= - -Talk about <sha1-file.c> and <object.h> family, things like - -* read_sha1_file() -* read_object_with_reference() -* has_sha1_file() -* write_sha1_file() -* pretend_object_file() -* lookup_{object,commit,tag,blob,tree} -* parse_{object,commit,tag,blob,tree} -* Use of object flags - -(JC, Shawn, Daniel, Dscho, Linus) diff --git a/Documentation/technical/api-quote.txt b/Documentation/technical/api-quote.txt deleted file mode 100644 index e8a1bce94e..0000000000 --- a/Documentation/technical/api-quote.txt +++ /dev/null @@ -1,10 +0,0 @@ -quote API -========= - -Talk about <quote.h>, things like - -* sq_quote and unquote -* c_style quote and unquote -* quoting for foreign languages - -(JC) diff --git a/Documentation/technical/api-xdiff-interface.txt b/Documentation/technical/api-xdiff-interface.txt deleted file mode 100644 index 6296ecad1d..0000000000 --- a/Documentation/technical/api-xdiff-interface.txt +++ /dev/null @@ -1,7 +0,0 @@ -xdiff interface API -=================== - -Talk about our calling convention to xdiff library, including -xdiff_emit_consume_fn. - -(Dscho, JC)