On Thu, Oct 24, 2019 at 10:44 AM Emily Shaffer <emilyshaffer@xxxxxxxxxx> wrote: > > On Wed, Oct 23, 2019 at 07:25:56AM +0000, Heba Waly via GitGitGadget wrote: > > From: Heba Waly <heba.waly@xxxxxxxxx> > > > > 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: > 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. That sounds better. Okay. > > 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. > > 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. yes. > - Emily Thanks
