git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH] config: Add documentation for writing config files

From
Tanay Abhra <tanayabh@gmail.com>
Date
Jun 3, 2014, 08:43 UTC
Message-ID
<538D8AB9.4010800@gmail.com>
In-Reply-To
<vpq38fnf6go.fsf@anie.imag.fr>
On 06/02/2014 12:37 PM, Matthieu Moy wrote:
Show 12 quoted lines
> Tanay Abhra <tanayabh@gmail.com> writes:
> 
>> Signed-off-by: Tanay Abhra <tanayabh@gmail.com>
>> ---
>>  Documentation/technical/api-config.txt | 31 ++++++++++++++++++++++++++++++-
>>  1 file changed, 30 insertions(+), 1 deletion(-)
> 
> Even though the reason to replace a TODO with real stuff is rather
> straigthforward, the reader appriates a short commit message (ideally
> pointing to the commit introducing the TODO). My first thought reading
> the patch was "wtf, is that a patch in the middle of a series, where
> does this TODO come from" ;-).
Ok, I will send a new patch with the updated commit message. .
Show 8 quoted lines
>> +In the end they both all call `git_config_set_multivar_in_file` which takes
>> +four parameters:
> 
> Do we really want to document this as part of the config API? i.e. does
> a normal user of the API want to know about this? My understanding is
> that git_config_set_multivar_in_file is essentially a private function,
> and then the best place to document is with comments near the function
> definition (it already has such comment).

Sorry, but I don't think so. In cache.h, the following functions have been provided as externs, git_config_set_in_file() git_config_set() git_config_set_multivar() git_config_set_multivar_in_file() extern int git_config_rename_section() extern int git_config_rename_section_in_file()

Thus, they seem to be the part of the API. In most of the technical API docs I have read there is at least a description of all parameters of the main function also, relevant data structures if any. Also a certain amount of redundancy about details is allowed.

A good example is api-hashmap.txt which provides detailed descriptions of each function and data structure which was very much helpful to me.

Reverse is api-string-list.txt which was useless to me, so I had to go through the whole code to understand how to use it.

Thanks for the review.
Previous: Matthieu Moy
Message 3 of 3 in “config: Add documentation for writing config files”
  1. config: Add documentation for writing config filesTanay Abhra, Jun 2, 2014
  2. Matthieu MoyJun 2, 2014
  3. Tanay AbhraJun 3, 2014

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.