[Outreachy] Intro
Hello everyone, My name is Heba and I’m one of the Outreachy applicants. I’ve selected the ‘moving the doc to comments’ microproject, and I’ll be submitting several patches addressing this area during the next week or two. The first one is already out there waiting for feedback (yey) https://public-inbox.org/git/pull.405.git.1571357219.gitgitgad...@gmail.com. I’m looking forward to working with you all. Heba Waly
Re: [PATCH 1/1] config: add documentation to config.h
On Sat, Oct 19, 2019 at 11:07 AM Jonathan Tan wrote:
>
> > From: Heba Waly
> >
> > This commit is copying and summarizing the documentation from
> > documentation/technical/api-config.txt to comments in config.h
>
> Thanks for this commit!
>
> As for your commit message, as far as I know, the idea is to move the
> documentation, not to copy it. Also, write this in imperative form,
> e.g.:
>
> Move the documentation from Documentation/technical/api-config.txt
> into config.h.
>
> Also change the title of the commit message accordingly, e.g.:
>
> config: move documentation to header file
>
Ok.
> Also, include the deletion of api-config.txt in this commit.
I wasn't sure if the api-config.txt should be removed or not so I
decided to keep it
and wait for feedback. I assume I'll need to delete api-config.html as well?
> If you are doing any summarizing, describe what summarizing you are
> doing in the commit message too.
Ok, will do so.
> > + * A config callback function takes three parameters:
> > + *
> > + * - the name of the parsed variable. This is in canonical "flat" form: the
> > + * section, subsection, and variable segments will be separated by dots,
> > + * and the section and variable segments will be all lowercase. E.g.,
> > + * `core.ignorecase`, `diff.SomeType.textconv`.
> > + *
> > + * - the value of the found variable, as a string. If the variable had no
> > + * value specified, the value will be NULL (typically this means it
> > + * should be interpreted as boolean true).
> > + *
> > + * - a void pointer passed in by the caller of the config API; this can
> > + * contain callback-specific data
> > + *
> > + * A config callback should return 0 for success, or -1 if the variable
> > + * could not be parsed properly.
> > + */
> > +
> > struct object_id;
> >
> > /* git_config_parse_key() returns these negated: */
> > @@ -73,6 +107,11 @@ struct config_options {
> >
> > typedef int (*config_fn_t)(const char *, const char *, void *);
> > int git_default_config(const char *, const char *, void *);
>
> The config callback is config_fn_t so that documentation should be
> placed above that typedef.
>
Cool, I couldn't find it, thanks!
> Other than that, this looks good to me. The result is perhaps not as
> tidy as we would like (especially with some functions being documented
> and others not) but I think, anyway, that a verbatim movement should be
> done in one commit (this one) and improvements, in a subsequent commit.
You're right, I would have loved to get all the functions documented, but that's
something I'm not able to do right now as I'm still getting familiar
with the code base.
But it's a good start!
I agree with you about moving the documentation and deleting the file
in one commit.
Will do so.
Thank you for the feedback!
Heba
Re: [PATCH 1/1] config: add documentation to config.h
On Sat, Oct 19, 2019 at 11:52 AM Emily Shaffer wrote: > > On Fri, Oct 18, 2019 at 12:06:59AM +, Heba Waly via GitGitGadget wrote: > > From: Heba Waly > > Hi Heba, > > Thanks for the patch! > > I'd like to highlight to the community that this is an Outreachy > applicant and microproject. Heba, when you send the next version, I > think you can add [Outreachy] manually to the PR subject line - that > should draw the attention of those in the community who are invested in > helping Outreachy applicants. Good idea! I wanted to add it to the email subject but as I decided to use gitgadget I had no control over the subject. > > > > This commit is copying and summarizing the documentation from > > documentation/technical/api-config.txt to comments in config.h > > I think in the GitGitGadget PR you've got some great comments from Dscho > about how to format your commit message; please take a look at those and > feel free to reach out to me if you're still not sure what's missing or > not. Will do. > > Signed-off-by: Heba Waly > > One thing I miss in this change is the removal of the contents of > Documentation/technical/api-config.txt (or maybe the removal of the file > itself). I'd prefer to see at least for api-config.txt to say something > like "Please refer to comments in 'config.h'"; or, more drastically, for > api-config.txt to be removed entirely. > > Having both pieces of documentation standing independently means that > someone who's trying to add new information about the config API won't > know where to add it; eventually they'll add something to config.h but > not api-config.txt, or vice versa, and the two documents will go out of > sync. So we want to move the documentation, rather than copy it. That makes sense, thanks for the explanation. I wasn't sure if it should be removed or not so I decided to leave it until I'm asked otherwise. So I assume api-config.html will be removed too? > Plus, having the removed doc as part of this change means I can more > easily look at where the lines of content are coming from and see if you > made any significant changes from the old contents of api-config.txt. > Having a smaller amount of change to review means your review will be > quicker - I don't feel as strong a need to check the grammar, spelling, > etc, because that text has already been reviewed before, and can just > make sure that the placement of each piece of documentation makes sense. yes! > > > --- > > config.h | 327 +++ > > 1 file changed, 327 insertions(+) > > > > diff --git a/config.h b/config.h > > index f0ed464004..fa999a2ba0 100644 > > --- a/config.h > > +++ b/config.h > > @@ -4,6 +4,40 @@ > > #include "hashmap.h" > > #include "string-list.h" > > > > + > > +/** > > + * The config API gives callers a way to access Git configuration files > > + * (and files which have the same syntax). See linkgit:git-config[1] for a > > + * discussion of the config file syntax. > > + * > > + * General Usage > > + * - > > + * > > + * Config files are parsed linearly, and each variable found is passed to a > > + * caller-provided callback function. The callback function is responsible > > + * for any actions to be taken on the config option, and is free to ignore > > + * some options. It is not uncommon for the configuration to be parsed > > + * several times during the run of a Git program, with different callbacks > > + * picking out different variables useful to themselves. > > + * > > + * A config callback function takes three parameters: > > + * > > + * - the name of the parsed variable. This is in canonical "flat" form: the > > + * section, subsection, and variable segments will be separated by dots, > > + * and the section and variable segments will be all lowercase. E.g., > > + * `core.ignorecase`, `diff.SomeType.textconv`. > > + * > > + * - the value of the found variable, as a string. If the variable had no > > + * value specified, the value will be NULL (typically this means it > > + * should be interpreted as boolean true). > > + * > > + * - a void pointer passed in by the caller of the config API; this can > > + * contain callback-specific data > > + * > > + * A config callback should return 0 for success, or -1 if the variable > > + * could not be parsed properly. > > + */ > > + > > struct object_id; > > > > /* git_config_parse_key() returns these negated: */ > > @@ -73,6 +1
Re: [PATCH v2 1/1] config: move documentation to config.h
On Wed, Oct 23, 2019 at 9:59 AM Emily Shaffer wrote: > > On Tue, Oct 22, 2019 at 07:05:06AM +, Heba Waly via GitGitGadget wrote: > > From: Heba Waly > > > > Move the documentation from Documentation/technical/api-config.txt into > > config.h > > This is still a little thin for what we usually want from commit > messages. Try to imagine that five years from now, you find this commit > by running `git blame` on config.h and then examining the commit which > introduced all these comments with `git show ` - what would > you want to know? > > Typically we want to know "why" the change was made, because the diff > shows "what". We can see from the diff that you're moving comments from > A to B, but if you explain why you did so (not "because my Outreachy > mentor told me to" ;) but "because it is useful to see usage information > next to code" or "this is best practice as described by blah blah") - I > wouldn't be able to know that reasoning just from looking at your diff. Ok, got it. > > > diff --git a/config.h b/config.h > > index f0ed464004..02f78ffc2b 100644 > > --- a/config.h > > +++ b/config.h > > @@ -4,6 +4,23 @@ > > #include "hashmap.h" > > #include "string-list.h" > > > > + > > +/** > > + * The config API gives callers a way to access Git configuration files > > + * (and files which have the same syntax). See linkgit:git-config[1] for a > > Ah, here's another place where the Asciidoc link isn't going to do > anything anymore. yep! > Otherwise I didn't still see anything jumping out. When the commit > message is cleaned up I'm ready to add my Reviewed-by line. great! > - Emily Thanks :)
Re: [PATCH 1/1] documentation: remove empty doc files
On Wed, Oct 23, 2019 at 10:05 AM Emily Shaffer wrote: > > On Tue, Oct 22, 2019 at 06:19:35PM +, Heba Waly via GitGitGadget wrote: > > From: Heba Waly > > > > 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 > > --- > > 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
Re: [PATCH 1/1] documentation: remove empty doc files
On Wed, Oct 23, 2019 at 12:52 PM Junio C Hamano wrote: > > Emily Shaffer 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
[PATCH 1/1] config: add documentation to config.h
From: Heba Waly
This commit is copying and summarizing the documentation from
documentation/technical/api-config.txt to comments in config.h
Signed-off-by: Heba Waly
---
config.h | 327 +++
1 file changed, 327 insertions(+)
diff --git a/config.h b/config.h
index f0ed464004..fa999a2ba0 100644
--- a/config.h
+++ b/config.h
@@ -4,6 +4,40 @@
#include "hashmap.h"
#include "string-list.h"
+
+/**
+ * The config API gives callers a way to access Git configuration files
+ * (and files which have the same syntax). See linkgit:git-config[1] for a
+ * discussion of the config file syntax.
+ *
+ * General Usage
+ * -
+ *
+ * Config files are parsed linearly, and each variable found is passed to a
+ * caller-provided callback function. The callback function is responsible
+ * for any actions to be taken on the config option, and is free to ignore
+ * some options. It is not uncommon for the configuration to be parsed
+ * several times during the run of a Git program, with different callbacks
+ * picking out different variables useful to themselves.
+ *
+ * A config callback function takes three parameters:
+ *
+ * - the name of the parsed variable. This is in canonical "flat" form: the
+ * section, subsection, and variable segments will be separated by dots,
+ * and the section and variable segments will be all lowercase. E.g.,
+ * `core.ignorecase`, `diff.SomeType.textconv`.
+ *
+ * - the value of the found variable, as a string. If the variable had no
+ * value specified, the value will be NULL (typically this means it
+ * should be interpreted as boolean true).
+ *
+ * - a void pointer passed in by the caller of the config API; this can
+ * contain callback-specific data
+ *
+ * A config callback should return 0 for success, or -1 if the variable
+ * could not be parsed properly.
+ */
+
struct object_id;
/* git_config_parse_key() returns these negated: */
@@ -73,6 +107,11 @@ struct config_options {
typedef int (*config_fn_t)(const char *, const char *, void *);
int git_default_config(const char *, const char *, void *);
+
+/**
+ * Read a specific file in git-config format.
+ * This function takes the same callback and data parameters as `git_config`.
+ */
int git_config_from_file(config_fn_t fn, const char *, void *);
int git_config_from_file_with_options(config_fn_t fn, const char *,
void *,
@@ -88,33 +127,152 @@ void git_config_push_parameter(const char *text);
int git_config_from_parameters(config_fn_t fn, void *data);
void read_early_config(config_fn_t cb, void *data);
void read_very_early_config(config_fn_t cb, void *data);
+
+/**
+ * Most programs will simply want to look up variables in all config files
+ * that Git knows about, using the normal precedence rules. To do this,
+ * call `git_config` with a callback function and void data pointer.
+ *
+ * `git_config` will read all config sources in order of increasing
+ * priority. Thus a callback should typically overwrite previously-seen
+ * entries with new ones (e.g., if both the user-wide `~/.gitconfig` and
+ * repo-specific `.git/config` contain `color.ui`, the config machinery
+ * will first feed the user-wide one to the callback, and then the
+ * repo-specific one; by overwriting, the higher-priority repo-specific
+ * value is left at the end).
+ */
void git_config(config_fn_t fn, void *);
+
+/**
+ * Lets the caller examine config while adjusting some of the default
+ * behavior of `git_config`. It should almost never be used by "regular"
+ * Git code that is looking up configuration variables.
+ * It is intended for advanced callers like `git-config`, which are
+ * intentionally tweaking the normal config-lookup process.
+ * It takes two extra parameters:
+ *
+ * `config_source`::
+ * If this parameter is non-NULL, it specifies the source to parse for
+ * configuration, rather than looking in the usual files. See `struct
+ * git_config_source` in `config.h` for details. Regular `git_config` defaults
+ * to `NULL`.
+ *
+ * `opts`::
+ * Specify options to adjust the behavior of parsing config files. See `struct
+ * config_options` in `config.h` for details. As an example: regular
`git_config`
+ * sets `opts.respect_includes` to `1` by default.
+ */
int config_with_options(config_fn_t fn, void *,
struct git_config_source *config_source,
const struct config_options *opts);
+
+/**
+ * Value Parsing Helpers
+ * -
+ *
+ * To aid in parsing string values, the config API provides callbacks with
+ * a number of helper functions
+ */
+
int git_parse_ssize_t(const char *, ssize_t *);
int git_parse_ulong(const char *, unsigned long *);
+
+/**
+ * Same as `git_config_bool`, except that it returns -1 on error rather
+ * than dying.
+ */
int git_parse_maybe_bool(const char *);
+
+/**
+ * Parse the string to an intege
[PATCH 0/1] config: add documentation to config.h
This commit is copying and summarizing the documentation from documentation/technical/api-config.txt to comments in config.h Signed-off-by: Heba Waly heba.w...@gmail.com [heba.w...@gmail.com] Thanks for taking the time to contribute to Git! Please be advised that the Git community does not use github.com for their contributions. Instead, we use a mailing list (git@vger.kernel.org) for code submissions, code reviews, and bug reports. Nevertheless, you can use GitGitGadget ( https://gitgitgadget.github.io/) to conveniently send your Pull Requests commits to our mailing list. Please read the "guidelines for contributing" linked above! Heba Waly (1): config: add documentation to config.h config.h | 327 +++ 1 file changed, 327 insertions(+) base-commit: 108b97dc372828f0e72e56bbb40cae8e1e83ece6 Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-405%2FHebaWaly%2Fconfig_documentation-v1 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-405/HebaWaly/config_documentation-v1 Pull-Request: https://github.com/gitgitgadget/git/pull/405 -- gitgitgadget
[PATCH v2 0/1] [Outreachy] config: move documentation to config.h
Move the documentation from Documentation/technical/api-config.txt into config.h Signed-off-by: Heba Waly heba.w...@gmail.com [heba.w...@gmail.com] Thanks for taking the time to contribute to Git! Please be advised that the Git community does not use github.com for their contributions. Instead, we use a mailing list (git@vger.kernel.org) for code submissions, code reviews, and bug reports. Nevertheless, you can use GitGitGadget ( https://gitgitgadget.github.io/) to conveniently send your Pull Requests commits to our mailing list. Please read the "guidelines for contributing" linked above! Heba Waly (1): config: move documentation to config.h Documentation/technical/api-config.txt | 319 --- config.h | 336 + 2 files changed, 336 insertions(+), 319 deletions(-) delete mode 100644 Documentation/technical/api-config.txt base-commit: 108b97dc372828f0e72e56bbb40cae8e1e83ece6 Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-405%2FHebaWaly%2Fconfig_documentation-v2 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-405/HebaWaly/config_documentation-v2 Pull-Request: https://github.com/gitgitgadget/git/pull/405 Range-diff vs v1: 1: 2e42eafb5d ! 1: 1a9aa33b46 config: add documentation to config.h @@ -1,12 +1,336 @@ Author: Heba Waly -config: add documentation to config.h - -This commit is copying and summarizing the documentation from -documentation/technical/api-config.txt to comments in config.h +config: move documentation to config.h +Move the documentation from Documentation/technical/api-config.txt into +config.h Signed-off-by: Heba Waly + diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt + deleted file mode 100644 + --- a/Documentation/technical/api-config.txt + +++ /dev/null +@@ +-config API +-== +- +-The config API gives callers a way to access Git configuration files +-(and files which have the same syntax). See linkgit:git-config[1] for a +-discussion of the config file syntax. +- +-General Usage +-- +- +-Config files are parsed linearly, and each variable found is passed to a +-caller-provided callback function. The callback function is responsible +-for any actions to be taken on the config option, and is free to ignore +-some options. It is not uncommon for the configuration to be parsed +-several times during the run of a Git program, with different callbacks +-picking out different variables useful to themselves. +- +-A config callback function takes three parameters: +- +-- the name of the parsed variable. This is in canonical "flat" form: the +- section, subsection, and variable segments will be separated by dots, +- and the section and variable segments will be all lowercase. E.g., +- `core.ignorecase`, `diff.SomeType.textconv`. +- +-- the value of the found variable, as a string. If the variable had no +- value specified, the value will be NULL (typically this means it +- should be interpreted as boolean true). +- +-- a void pointer passed in by the caller of the config API; this can +- contain callback-specific data +- +-A config callback should return 0 for success, or -1 if the variable +-could not be parsed properly. +- +-Basic Config Querying +-- +- +-Most programs will simply want to look up variables in all config files +-that Git knows about, using the normal precedence rules. To do this, +-call `git_config` with a callback function and void data pointer. +- +-`git_config` will read all config sources in order of increasing +-priority. Thus a callback should typically overwrite previously-seen +-entries with new ones (e.g., if both the user-wide `~/.gitconfig` and +-repo-specific `.git/config` contain `color.ui`, the config machinery +-will first feed the user-wide one to the callback, and then the +-repo-specific one; by overwriting, the higher-priority repo-specific +-value is left at the end). +- +-The `config_with_options` function lets the caller examine config +-while adjusting some of the default behavior of `git_config`. It should +-almost never be used by "regular" Git code that is looking up +-configuration variables. It is intended for advanced callers like +-`git-config`, which are intentionally tweaking the normal config-lookup +-process. It takes two extra parameters: +- +-`config_source`:: +-If this parameter is non-NULL, it specifies the source to parse for +-configuration, rather than looking in the usual files. See `s
[PATCH v2 1/1] config: move documentation to config.h
From: Heba Waly Move the documentation from Documentation/technical/api-config.txt into config.h Signed-off-by: Heba Waly --- Documentation/technical/api-config.txt | 319 --- config.h | 336 + 2 files changed, 336 insertions(+), 319 deletions(-) delete mode 100644 Documentation/technical/api-config.txt diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt deleted file mode 100644 index 7d20716c32..00 --- a/Documentation/technical/api-config.txt +++ /dev/null @@ -1,319 +0,0 @@ -config API -== - -The config API gives callers a way to access Git configuration files -(and files which have the same syntax). See linkgit:git-config[1] for a -discussion of the config file syntax. - -General Usage -- - -Config files are parsed linearly, and each variable found is passed to a -caller-provided callback function. The callback function is responsible -for any actions to be taken on the config option, and is free to ignore -some options. It is not uncommon for the configuration to be parsed -several times during the run of a Git program, with different callbacks -picking out different variables useful to themselves. - -A config callback function takes three parameters: - -- the name of the parsed variable. This is in canonical "flat" form: the - section, subsection, and variable segments will be separated by dots, - and the section and variable segments will be all lowercase. E.g., - `core.ignorecase`, `diff.SomeType.textconv`. - -- the value of the found variable, as a string. If the variable had no - value specified, the value will be NULL (typically this means it - should be interpreted as boolean true). - -- a void pointer passed in by the caller of the config API; this can - contain callback-specific data - -A config callback should return 0 for success, or -1 if the variable -could not be parsed properly. - -Basic Config Querying -- - -Most programs will simply want to look up variables in all config files -that Git knows about, using the normal precedence rules. To do this, -call `git_config` with a callback function and void data pointer. - -`git_config` will read all config sources in order of increasing -priority. Thus a callback should typically overwrite previously-seen -entries with new ones (e.g., if both the user-wide `~/.gitconfig` and -repo-specific `.git/config` contain `color.ui`, the config machinery -will first feed the user-wide one to the callback, and then the -repo-specific one; by overwriting, the higher-priority repo-specific -value is left at the end). - -The `config_with_options` function lets the caller examine config -while adjusting some of the default behavior of `git_config`. It should -almost never be used by "regular" Git code that is looking up -configuration variables. It is intended for advanced callers like -`git-config`, which are intentionally tweaking the normal config-lookup -process. It takes two extra parameters: - -`config_source`:: -If this parameter is non-NULL, it specifies the source to parse for -configuration, rather than looking in the usual files. See `struct -git_config_source` in `config.h` for details. Regular `git_config` defaults -to `NULL`. - -`opts`:: -Specify options to adjust the behavior of parsing config files. See `struct -config_options` in `config.h` for details. As an example: regular `git_config` -sets `opts.respect_includes` to `1` by default. - -Reading Specific Files --- - -To read a specific file in git-config format, use -`git_config_from_file`. This takes the same callback and data parameters -as `git_config`. - -Querying For Specific Variables - -For programs wanting to query for specific variables in a non-callback -manner, the config API provides two functions `git_config_get_value` -and `git_config_get_value_multi`. They both read values from an internal -cache generated previously from reading the config files. - -`int git_config_get_value(const char *key, const char **value)`:: - - Finds the highest-priority value for the configuration variable `key`, - stores the pointer to it in `value` and returns 0. When the - configuration variable `key` is not found, returns 1 without touching - `value`. The caller should not free or modify `value`, as it is owned - by the cache. - -`const struct string_list *git_config_get_value_multi(const char *key)`:: - - Finds and returns the value list, sorted in order of increasing priority - for the configuration variable `key`. When the configuration variable - `key` is not found, returns NULL. The caller should not free or modify - the returned pointer, as it is owned by the cache. - -`void git_config_clear(void)`:: - - Resets and invalidates the config cache. - -The config API also provides type sp
[PATCH 1/1] documentation: remove empty doc files
From: Heba Waly
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
Signed-off-by: Heba Waly
---
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
diff --git a/Documentation/technical/api-grep.txt
b/Documentation/technical/api-grep.txt
deleted file mode 100644
index a69cc8964d..00
--- a/Documentation/technical/api-grep.txt
+++ /dev/null
@@ -1,8 +0,0 @@
-grep API
-
-
-Talk about , 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..00
--- a/Documentation/technical/api-object-access.txt
+++ /dev/null
@@ -1,15 +0,0 @@
-object access API
-=
-
-Talk about and 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..00
--- a/Documentation/technical/api-quote.txt
+++ /dev/null
@@ -1,10 +0,0 @@
-quote API
-=
-
-Talk about , 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..00
--- 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)
--
gitgitgadget
[PATCH 0/1] [Outreachy] 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 Signed-off-by: Heba Waly heba.w...@gmail.com [heba.w...@gmail.com] 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
[PATCH v3 1/1] config: move documentation to config.h
From: Heba Waly Move the documentation from Documentation/technical/api-config.txt into config.h as it's easier for the developers to find the usage information beside the code instead of looking for it in another doc file, also documentation/technical/api-config.txt is removed because the information it has is now redundant and it'll be hard to keep it up to date and syncronized with the documentation in config.h Signed-off-by: Heba Waly --- Documentation/technical/api-config.txt | 319 --- config.h | 335 + 2 files changed, 335 insertions(+), 319 deletions(-) delete mode 100644 Documentation/technical/api-config.txt diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt deleted file mode 100644 index 7d20716c32..00 --- a/Documentation/technical/api-config.txt +++ /dev/null @@ -1,319 +0,0 @@ -config API -== - -The config API gives callers a way to access Git configuration files -(and files which have the same syntax). See linkgit:git-config[1] for a -discussion of the config file syntax. - -General Usage -- - -Config files are parsed linearly, and each variable found is passed to a -caller-provided callback function. The callback function is responsible -for any actions to be taken on the config option, and is free to ignore -some options. It is not uncommon for the configuration to be parsed -several times during the run of a Git program, with different callbacks -picking out different variables useful to themselves. - -A config callback function takes three parameters: - -- the name of the parsed variable. This is in canonical "flat" form: the - section, subsection, and variable segments will be separated by dots, - and the section and variable segments will be all lowercase. E.g., - `core.ignorecase`, `diff.SomeType.textconv`. - -- the value of the found variable, as a string. If the variable had no - value specified, the value will be NULL (typically this means it - should be interpreted as boolean true). - -- a void pointer passed in by the caller of the config API; this can - contain callback-specific data - -A config callback should return 0 for success, or -1 if the variable -could not be parsed properly. - -Basic Config Querying -- - -Most programs will simply want to look up variables in all config files -that Git knows about, using the normal precedence rules. To do this, -call `git_config` with a callback function and void data pointer. - -`git_config` will read all config sources in order of increasing -priority. Thus a callback should typically overwrite previously-seen -entries with new ones (e.g., if both the user-wide `~/.gitconfig` and -repo-specific `.git/config` contain `color.ui`, the config machinery -will first feed the user-wide one to the callback, and then the -repo-specific one; by overwriting, the higher-priority repo-specific -value is left at the end). - -The `config_with_options` function lets the caller examine config -while adjusting some of the default behavior of `git_config`. It should -almost never be used by "regular" Git code that is looking up -configuration variables. It is intended for advanced callers like -`git-config`, which are intentionally tweaking the normal config-lookup -process. It takes two extra parameters: - -`config_source`:: -If this parameter is non-NULL, it specifies the source to parse for -configuration, rather than looking in the usual files. See `struct -git_config_source` in `config.h` for details. Regular `git_config` defaults -to `NULL`. - -`opts`:: -Specify options to adjust the behavior of parsing config files. See `struct -config_options` in `config.h` for details. As an example: regular `git_config` -sets `opts.respect_includes` to `1` by default. - -Reading Specific Files --- - -To read a specific file in git-config format, use -`git_config_from_file`. This takes the same callback and data parameters -as `git_config`. - -Querying For Specific Variables - -For programs wanting to query for specific variables in a non-callback -manner, the config API provides two functions `git_config_get_value` -and `git_config_get_value_multi`. They both read values from an internal -cache generated previously from reading the config files. - -`int git_config_get_value(const char *key, const char **value)`:: - - Finds the highest-priority value for the configuration variable `key`, - stores the pointer to it in `value` and returns 0. When the - configuration variable `key` is not found, returns 1 without touching - `value`. The caller should not free or modify `value`, as it is owned - by the cache. - -`const struct string_list *git_config_get_value_multi(const char *key)`:: - - Finds and returns the value list, sorted in order of increasing priority - for t
[PATCH v3 0/1] [Outreachy] config: move documentation to config.h
Move the documentation from Documentation/technical/api-config.txt into config.h as it's easier for the developers to find the usage information beside the code instead of looking for it in another doc file, also documentation/technical/api-config.txt is removed because the information it has is now redundant and it'll be hard to keep it up to date and synchronized with the documentation in config.h Signed-off-by: Heba Waly heba.w...@gmail.com [heba.w...@gmail.com] Heba Waly (1): config: move documentation to config.h Documentation/technical/api-config.txt | 319 --- config.h | 335 + 2 files changed, 335 insertions(+), 319 deletions(-) delete mode 100644 Documentation/technical/api-config.txt base-commit: 108b97dc372828f0e72e56bbb40cae8e1e83ece6 Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-405%2FHebaWaly%2Fconfig_documentation-v3 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-405/HebaWaly/config_documentation-v3 Pull-Request: https://github.com/gitgitgadget/git/pull/405 Range-diff vs v2: 1: 1a9aa33b46 ! 1: d6cbb3197a config: move documentation to config.h @@ -3,7 +3,12 @@ config: move documentation to config.h Move the documentation from Documentation/technical/api-config.txt into -config.h +config.h as it's easier for the developers to find the usage information +beside the code instead of looking for it in another doc file, also +documentation/technical/api-config.txt is removed because the information +it has is now redundant and it'll be hard to keep it up to date and +syncronized with the documentation in config.h + Signed-off-by: Heba Waly diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt @@ -341,8 +346,7 @@ + +/** + * The config API gives callers a way to access Git configuration files -+ * (and files which have the same syntax). See linkgit:git-config[1] for a -+ * discussion of the config file syntax. ++ * (and files which have the same syntax). + * + * General Usage + * - -- gitgitgadget
[PATCH v2 1/1] documentation: remove empty doc files
From: Heba Waly
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.
Signed-off-by: Heba Waly
---
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
diff --git a/Documentation/technical/api-grep.txt
b/Documentation/technical/api-grep.txt
deleted file mode 100644
index a69cc8964d..00
--- a/Documentation/technical/api-grep.txt
+++ /dev/null
@@ -1,8 +0,0 @@
-grep API
-
-
-Talk about , 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..00
--- a/Documentation/technical/api-object-access.txt
+++ /dev/null
@@ -1,15 +0,0 @@
-object access API
-=
-
-Talk about and 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..00
--- a/Documentation/technical/api-quote.txt
+++ /dev/null
@@ -1,10 +0,0 @@
-quote API
-=
-
-Talk about , 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..00
--- 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)
--
gitgitgadget
[PATCH v2 0/1] [Outreachy] documentation: remove empty doc files
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.
Signed-off-by: Heba Waly heba.w...@gmail.com [heba.w...@gmail.com]
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.
Signed-off-by: Heba Waly
--
gitgitgadget
