Re: [Tarantool-patches] [PATCH 1/2] sql: refactor index drop code

[Vladislav Shpilevoy <v.shpilevoy@tarantool.org>]

On 30/01/2020 12:12, Nikita Pettik wrote:
> On 30 Jan 00:45, Vladislav Shpilevoy wrote:
>>
>>
>> On 29/01/2020 23:32, Nikita Pettik wrote:
>>> On 29 Jan 22:56, Vladislav Shpilevoy wrote:
>>>>>> diff --git a/src/box/sql/build.c b/src/box/sql/build.c
>>>>>> index bc50ecbfa..58a6a8a6b 100644
>>>>>> --- a/src/box/sql/build.c
>>>>>> +++ b/src/box/sql/build.c
>>>>>> @@ -1469,6 +1469,26 @@ vdbe_emit_stat_space_clear(struct Parse *parse, const char *stat_table_name,
>>>>>>  	sql_table_delete_from(parse, src_list, where);
>>>>>>  }
>>>>>>  
>>>>>> +/**
>>>>>> + * Generate VDBE program to remove entry with @a index_id and @a
>>>>>> + * space_id from _index space.
>>>>>
>>>>> Is @a common shortcat for @param? If so, please share a link to docs,
>>>>> since I've managed to find only this:
>>>>> '''
>>>>> \a <word>
>>>>> Displays the argument in italics. Use this command to emphasize words.
>>>>> Use this command to refer to member arguments in the running text.
>>>>> '''
>>>>
>>>> We use @param when describe parameters. In @brief sections we use @a
>>>> intentionally. Probably because
>>>>
>>>> 1) @param is used to attach a description to a paramter, and for
>>>> nothing else: http://www.doxygen.nl/manual/commands.html#cmdparam
>>>>
>>>> 2) @a is just shorter, and we can use parameter name multiple times
>>>> in @brief, so it is important.
>>>
>>> Is this undocumented doxygen feature?:) I failed to find out any description
>>> of '@a' command except for the one I posted above. Or this is purely Tarantool's
>>> codestyle convention?	
>>
>> Why undocumented? It is documented, and you've found a correct description.
>> @a is just an italic font for a next word. It is not for parameter names
>> only, and is not related to @param. We use it so as parameter names in
>> function descriptions would be highlighted somehow. Don't know why exactly
>> @a was chosen instead of, for example, @b (bold) or @c (typewriter font).
> 
> At least our docs say nothing about this convention:
> 
> https://www.tarantool.io/en/doc/2.2/dev_guide/c_style_guide/#commenting-style

Our docs don't say many things, but it does not mean they don't
exist. We use @a throughout all our code base. If you want, you
can file a doc ticket on that.