documentation: remove empty doc files

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: Documentation/technical/api-grep.txt Documentation/technical/api-object-access.txt Documentation/technical/api-quote.txt Documentation/technical/api-xdiff-interface.txt

Heba Waly (1):
documentation: remove empty doc files

 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

base-commit: d966095db01190a2196e31195ea6fa0c722aa732
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-412%2FHebaWaly%2Fdelete_empty_docs-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-412/HebaWaly/delete_empty_docs-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/412

gitgitgadget

From: Heba Waly <[email protected]>

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

---
 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

deleted file mode 100644
index a69cc8964d..0000000000
@@ -1,8 +0,0 @@
-grep API
-========
-
-Talk about <grep.h>, things like:
-
-* grep_buffer()
-
-(JC)

deleted file mode 100644
index 5b29622d00..0000000000
@@ -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)

deleted file mode 100644
index e8a1bce94e..0000000000
@@ -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)

deleted file mode 100644
index 6296ecad1d..0000000000
@@ -1,7 +0,0 @@
-xdiff interface API
-===================
-
-Talk about our calling convention to xdiff library, including
-xdiff_emit_consume_fn.
-
-(Dscho, JC)

gitgitgadget

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.

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

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

you're right!

Good point, although not all corresponding header files are documented, but I'll include that in the commit message.

Thanks

Remove empty and redundant documentation files from the Documentation/technical/ directory.

The empty doc files included only TODO messages with no documentation for years. Instead an approach is being taken to keep all doc beside the code in the relevant header files. Having empty doc files is confusing and disappointing to anybody looking for information, besides having the documentation in header files makes it easier for developers to find the information they are looking for.

here's a list of the files removed and if the info can be found in the corresponding header file: 1- Documentation/technical/api-grep.txt -> grep.h does not have enough documentation at the moment. 2- Documentation/technical/api-object-access.txt -> sha1-file.c and object.h have some details 3- Documentation/technical/api-quote.txt -> quote.h has some details. 4- Documentation/technical/api-xdiff-interface.txt -> xdiff-interface.h has some details.

Heba Waly (1):
documentation: remove empty doc files

 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

base-commit: d966095db01190a2196e31195ea6fa0c722aa732
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-412%2FHebaWaly%2Fdelete_empty_docs-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-412/HebaWaly/delete_empty_docs-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/412

Range-diff vs v1:

1: ffdde613d8 ! 1: 5cd79e24fe documentation: remove empty doc files
@@ -5,13 +5,22 @@
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
+ The empty doc files included only TODO messages with no documentation for
+ years. Instead an approach is being taken to keep all doc beside the code
+ in the relevant header files.
+ Having empty doc files is confusing and disappointing to anybody looking
+ for information, besides having the documentation in header files makes it
+ easier for developers to find the information they are looking for.
+
+ here's a list of the files removed and if the info can be found in the
+ corresponding header file:
+ 1- Documentation/technical/api-grep.txt -> grep.h does not have enough
+ documentation at the moment.
+ 2- Documentation/technical/api-object-access.txt -> sha1-file.c and
+ object.h have some details
+ 3- Documentation/technical/api-quote.txt -> quote.h has some details.
+ 4- Documentation/technical/api-xdiff-interface.txt -> xdiff-interface.h has
+ some details.

gitgitgadget

From: Heba Waly <[email protected]>

Remove empty and redundant documentation files from the Documentation/technical/ directory.

The empty doc files included only TODO messages with no documentation for years. Instead an approach is being taken to keep all doc beside the code in the relevant header files.
Having empty doc files is confusing and disappointing to anybody looking for information, besides having the documentation in header files makes it easier for developers to find the information they are looking for.

here's a list of the files removed and if the info can be found in the corresponding header file:
1- Documentation/technical/api-grep.txt -> grep.h does not have enough documentation at the moment.
2- Documentation/technical/api-object-access.txt -> sha1-file.c and object.h have some details
3- Documentation/technical/api-quote.txt -> quote.h has some details. 4- Documentation/technical/api-xdiff-interface.txt -> xdiff-interface.h has some details.

---
 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

deleted file mode 100644
index a69cc8964d..0000000000
@@ -1,8 +0,0 @@
-grep API
-========
-
-Talk about <grep.h>, things like:
-
-* grep_buffer()
-
-(JC)

deleted file mode 100644
index 5b29622d00..0000000000
@@ -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)

deleted file mode 100644
index e8a1bce94e..0000000000
@@ -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)

deleted file mode 100644
index 6296ecad1d..0000000000
@@ -1,7 +0,0 @@
-xdiff interface API
-===================
-
-Talk about our calling convention to xdiff library, including
-xdiff_emit_consume_fn.
-
-(Dscho, JC)

gitgitgadget

I think you can remove the above; in lots of composition contexts it tends to be bad form to say "Here is <something>: <something>" - don't warn us that you're going to present it, just present it. :) (Or, at least, this has been drilled into my head by many high school English teachers...)

Maybe you could say something like, "Some of the content which could have gone here already exists elsewhere:" If you take that suggestion, you can probably move grep.h to the bottom, as it's the exception which doesn't have content that exists elsewhere.

For this list, I think you can remove the numbered bullet, and the leading "Documentation/technical/" - we can see the files deleted from the diff.

- Emily

That sounds better. Okay.

yes.

Thanks

Remove empty and redundant documentation files from the Documentation/technical/ directory.

The empty doc files included only TODO messages with no documentation for years. Instead an approach is being taken to keep all doc beside the code in the relevant header files. Having empty doc files is confusing and disappointing to anybody looking for information, besides having the documentation in header files makes it easier for developers to find the information they are looking for.

Some of the content which could have gone here already exists elsewhere:

* api-object-access.txt -> sha1-file.c and object.h have some details.
* api-quote.txt -> quote.h has some details.
* api-xdiff-interface.txt -> xdiff-interface.h has some details.
* api-grep.txt -> grep.h does not have enough documentation at the moment.

Heba Waly (1):
documentation: remove empty doc files

 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

base-commit: d966095db01190a2196e31195ea6fa0c722aa732
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-412%2FHebaWaly%2Fdelete_empty_docs-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-412/HebaWaly/delete_empty_docs-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/412

Range-diff vs v2:

1: 5cd79e24fe ! 1: ee64a075d3 documentation: remove empty doc files
@@ -12,15 +12,11 @@
for information, besides having the documentation in header files makes it easier for developers to find the information they are looking for.

- here's a list of the files removed and if the info can be found in the
- corresponding header file:
- 1- Documentation/technical/api-grep.txt -> grep.h does not have enough
- documentation at the moment.
- 2- Documentation/technical/api-object-access.txt -> sha1-file.c and
- object.h have some details
- 3- Documentation/technical/api-quote.txt -> quote.h has some details.
- 4- Documentation/technical/api-xdiff-interface.txt -> xdiff-interface.h has
- some details.
+ Some of the content which could have gone here already exists elsewhere:
+ - api-object-access.txt -> sha1-file.c and object.h have some details.
+ - api-quote.txt -> quote.h has some details.
+ - api-xdiff-interface.txt -> xdiff-interface.h has some details.
+ - api-grep.txt -> grep.h does not have enough documentation at the moment.

gitgitgadget

From: Heba Waly <[email protected]>

Remove empty and redundant documentation files from the Documentation/technical/ directory.

The empty doc files included only TODO messages with no documentation for years. Instead an approach is being taken to keep all doc beside the code in the relevant header files.
Having empty doc files is confusing and disappointing to anybody looking for information, besides having the documentation in header files makes it easier for developers to find the information they are looking for.

Some of the content which could have gone here already exists elsewhere:
- api-object-access.txt -> sha1-file.c and object.h have some details.
- api-quote.txt -> quote.h has some details.
- api-xdiff-interface.txt -> xdiff-interface.h has some details.
- api-grep.txt -> grep.h does not have enough documentation at the moment.

---
 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

deleted file mode 100644
index a69cc8964d..0000000000
@@ -1,8 +0,0 @@
-grep API
-========
-
-Talk about <grep.h>, things like:
-
-* grep_buffer()
-
-(JC)

deleted file mode 100644
index 5b29622d00..0000000000
@@ -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)

deleted file mode 100644
index e8a1bce94e..0000000000
@@ -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)

deleted file mode 100644
index 6296ecad1d..0000000000
@@ -1,7 +0,0 @@
-xdiff interface API
-===================
-
-Talk about our calling convention to xdiff library, including
-xdiff_emit_consume_fn.
-
-(Dscho, JC)

gitgitgadget

Thanks, Heba.
- Emily