[PATCH] doc: fix config API documentation about config_with_options

[PATCH] doc: fix config API documentation about config_with_options

[Antonio Ospite]

In commit dc8441fdb ("config: don't implicitly use gitdir or commondir",
2017-06-14) the function git_config_with_options was renamed to
config_with_options to better reflect the fact that it does not access
the git global config or the repo config by default.

However Documentation/technical/api-config.txt still refers to the
previous name, fix that.

While at it also update the documentation about the extra parameters,
because they too changed since the initial definition.

Signed-off-by: Antonio Ospite <ao2@ao2.it>
---

Patch based on the maint branch.

Ciao,
   Antonio

 Documentation/technical/api-config.txt | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt
index 9a778b0ca..fa39ac9d7 100644
--- a/Documentation/technical/api-config.txt
+++ b/Documentation/technical/api-config.txt
@@ -47,21 +47,23 @@ 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 `git_config_with_options` function lets the caller examine config
+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:
 
-`filename`::
-If this parameter is non-NULL, it specifies the name of a file to
-parse for configuration, rather than looking in the usual files. Regular
-`git_config` defaults to `NULL`.
+`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`.
 
-`respect_includes`::
-Specify whether include directives should be followed in parsed files.
-Regular `git_config` defaults to `1`.
+`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
 ----------------------
-- 
2.17.0

Re: [PATCH] doc: fix config API documentation about config_with_options

[Brandon Williams]

On 05/09, Antonio Ospite wrote:
> In commit dc8441fdb ("config: don't implicitly use gitdir or commondir",
> 2017-06-14) the function git_config_with_options was renamed to
> config_with_options to better reflect the fact that it does not access
> the git global config or the repo config by default.
> 
> However Documentation/technical/api-config.txt still refers to the
> previous name, fix that.
> 
> While at it also update the documentation about the extra parameters,
> because they too changed since the initial definition.
> 
> Signed-off-by: Antonio Ospite <ao2@ao2.it>
> ---
> 
> Patch based on the maint branch.

Thanks for updating the docs.  Maybe one day we can migrate these docs
to the source files themselves, making it easier to keep up to date.
For now this is good :)

> 
> Ciao,
>    Antonio
> 
>  Documentation/technical/api-config.txt | 18 ++++++++++--------
>  1 file changed, 10 insertions(+), 8 deletions(-)
> 
> diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt
> index 9a778b0ca..fa39ac9d7 100644
> --- a/Documentation/technical/api-config.txt
> +++ b/Documentation/technical/api-config.txt
> @@ -47,21 +47,23 @@ 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 `git_config_with_options` function lets the caller examine config
> +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:
>  
> -`filename`::
> -If this parameter is non-NULL, it specifies the name of a file to
> -parse for configuration, rather than looking in the usual files. Regular
> -`git_config` defaults to `NULL`.
> +`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`.
>  
> -`respect_includes`::
> -Specify whether include directives should be followed in parsed files.
> -Regular `git_config` defaults to `1`.
> +`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
>  ----------------------
> -- 
> 2.17.0
> 

-- 
Brandon Williams

Re: [PATCH] doc: fix config API documentation about config_with_options

[Antonio Ospite]

On Wed, 9 May 2018 10:19:50 -0700
Brandon Williams <bmwill@google.com> wrote:

> On 05/09, Antonio Ospite wrote:
> > In commit dc8441fdb ("config: don't implicitly use gitdir or commondir",
> > 2017-06-14) the function git_config_with_options was renamed to
> > config_with_options to better reflect the fact that it does not access
> > the git global config or the repo config by default.
> > 
> > However Documentation/technical/api-config.txt still refers to the
> > previous name, fix that.
> > 
> > While at it also update the documentation about the extra parameters,
> > because they too changed since the initial definition.
> > 
> > Signed-off-by: Antonio Ospite <ao2@ao2.it>
> > ---
> > 
> > Patch based on the maint branch.
> 
> Thanks for updating the docs.  Maybe one day we can migrate these docs
> to the source files themselves, making it easier to keep up to date.
> For now this is good :)
> 

Should I resend the patch to gitster@pobox.com with your Acked-by?

Thanks,
   Antonio

-- 
Antonio Ospite
https://ao2.it
https://twitter.com/ao2it

A: Because it messes up the order in which people normally read text.
   See http://en.wikipedia.org/wiki/Posting_style
Q: Why is top-posting such a bad thing?

Re: [PATCH] doc: fix config API documentation about config_with_options

[Junio C Hamano]

Brandon Williams <bmwill@google.com> writes:

> On 05/09, Antonio Ospite wrote:
>> In commit dc8441fdb ("config: don't implicitly use gitdir or commondir",
>> 2017-06-14) the function git_config_with_options was renamed to
>> config_with_options to better reflect the fact that it does not access
>> the git global config or the repo config by default.
>> 
>> However Documentation/technical/api-config.txt still refers to the
>> previous name, fix that.
>> 
>> While at it also update the documentation about the extra parameters,
>> because they too changed since the initial definition.
>> 
>> Signed-off-by: Antonio Ospite <ao2@ao2.it>
>> ---
>> 
>> Patch based on the maint branch.
>
> Thanks for updating the docs.  Maybe one day we can migrate these docs
> to the source files themselves, making it easier to keep up to date.
> For now this is good :)

Thanks, both.

Re: [PATCH] doc: fix config API documentation about config_with_options

[Brandon Williams]

On 05/12, Antonio Ospite wrote:
> On Wed, 9 May 2018 10:19:50 -0700
> Brandon Williams <bmwill@google.com> wrote:
> 
> > On 05/09, Antonio Ospite wrote:
> > > In commit dc8441fdb ("config: don't implicitly use gitdir or commondir",
> > > 2017-06-14) the function git_config_with_options was renamed to
> > > config_with_options to better reflect the fact that it does not access
> > > the git global config or the repo config by default.
> > > 
> > > However Documentation/technical/api-config.txt still refers to the
> > > previous name, fix that.
> > > 
> > > While at it also update the documentation about the extra parameters,
> > > because they too changed since the initial definition.
> > > 
> > > Signed-off-by: Antonio Ospite <ao2@ao2.it>
> > > ---
> > > 
> > > Patch based on the maint branch.
> > 
> > Thanks for updating the docs.  Maybe one day we can migrate these docs
> > to the source files themselves, making it easier to keep up to date.
> > For now this is good :)
> > 
> 
> Should I resend the patch to gitster@pobox.com with your Acked-by?

This has my Reviewed-by: Brandon Williams <bmwill@google.com>
though you don't need to resend the patch to Junio, he has normally
taken care of that :)

> 
> Thanks,
>    Antonio
> 
> -- 
> Antonio Ospite
> https://ao2.it
> https://twitter.com/ao2it
> 
> A: Because it messes up the order in which people normally read text.
>    See http://en.wikipedia.org/wiki/Posting_style
> Q: Why is top-posting such a bad thing?

-- 
Brandon Williams