[SSSD] [PATCH][ding-libs] DOC: Fix problems in documentation comments

Lukas Slebodnik lslebodn at redhat.com
Tue Jan 21 13:39:28 UTC 2014


On (21/01/14 08:30), Dmitri Pal wrote:
>On 01/21/2014 06:26 AM, Lukas Slebodnik wrote:
>> ehlo,
>>
>> self describing patch is attached.
>>
>> LS
>>
>> 0001-DOC-Fix-problems-in-documentation-comments.patch
>>
>>
>> From bfcd145a400799caf359f0a37d2d816041245abb Mon Sep 17 00:00:00 2001
>> From: Lukas Slebodnik <lslebodn at redhat.com>
>> Date: Tue, 21 Jan 2014 12:23:24 +0100
>> Subject: [PATCH] DOC: Fix problems in documentation comments.
>>
>> void functions needn't have "@return" comment. We was not consistent.
>> Fix problems with parameter names
>> ---
>>  collection/collection.h | 7 -------
>>  ini/ini_print.c         | 4 ++--
>>  2 files changed, 2 insertions(+), 9 deletions(-)
>>
>> diff --git a/collection/collection.h b/collection/collection.h
>> index 48b28cc7ebfe0c17cedbddb55a40806bf579b886..0dd2f9000e718eaacb4500b9cf9a6423485a4c95 100644
>> --- a/collection/collection.h
>> +++ b/collection/collection.h
>> @@ -502,7 +502,6 @@ void col_destroy_collection(struct collection_item *ci);
>>   *                           this parameter.
>>   * @param[in]  custom_data   Custom data will be passed in
>>   *                           this parameter.
>> - * @return No return value.
>>   */
>>  
>
>This makes sense.
>
>>  typedef void (*col_item_cleanup_fn)(const char *property,
>> @@ -3210,9 +3209,6 @@ int col_get_item_depth(struct collection_iterator *iterator, int *depth);
>>   * It is a 20% comparison reduction.
>>   *
>>   * @param[in]  iterator   Iterator object to use.
>> - *
>> - * @return 0          - Success.
>> - * @return EINVAL     - The value of the argument is invalid.
>>   */
>
>This is not correct.
>Function would fail if invalid object is passed.
>Depth is returned in the passed in output argument not as a return value.
>This change is not needed.
>
The previous comment is to the function col_pin_iterator with prototype:
  void col_pin_iterator(struct collection_iterator *iterator);

Did I misunderstand something?

LS

>>  void col_pin_iterator(struct collection_iterator *iterator);
>>  
>> @@ -3224,9 +3220,6 @@ void col_pin_iterator(struct collection_iterator *iterator);
>>   * \ref col_pin_iterator function.
>>   *
>>   * @param[in]  iterator   Iterator object to use.
>> - *
>> - * @return 0          - Success.
>> - * @return EINVAL     - The value of the argument is invalid.
>>   */
>
>Makes sense
>
>>  void col_rewind_iterator(struct collection_iterator *iterator);
>>  
>> diff --git a/ini/ini_print.c b/ini/ini_print.c
>> index 62b20ff932a9d5f34be41327c75f7c10065f20ae..d9e847380b5f0c59e9112d345388cee68b624e76 100644
>> --- a/ini/ini_print.c
>> +++ b/ini/ini_print.c
>> @@ -155,7 +155,7 @@ static const char *parsing_error_str(int parsing_error)
>>   * This error is returned when the template
>>   * is translated into the grammar object.
>>   *
>> - * @param[in] parsing_error    Error code for the grammar error.
>> + * @param[in] grammar_error    Error code for the grammar error.
>>   *
>>   * @return Error string.
>
>Fine, though it is an internal function.
>
>>   */
>> @@ -197,7 +197,7 @@ static const char *grammar_error_str(int grammar_error)
>>   * the INI file is validated against the
>>   * grammar object.
>>   *
>> - * @param[in] parsing_error    Error code for the validation error.
>> + * @param[in] validation_error    Error code for the validation error.
>>   *
>>   * @return Error string.
>>   */
>
>Same here.
>
>
>
>> -- 1.8.4.2



More information about the sssd-devel mailing list