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

Dmitri Pal dpal at redhat.com
Tue Jan 21 14:13:38 UTC 2014


On 01/21/2014 08:39 AM, Lukas Slebodnik wrote:
> 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

No, actually I misread it. I thought it is for col_get_item_depth

Then it seems OK. I am not giving a formal ack because I did not try to
apply the actual patch.

>>>  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


-- 
Thank you,
Dmitri Pal

Sr. Engineering Manager for IdM portfolio
Red Hat Inc.


-------------------------------
Looking to carve out IT costs?
www.redhat.com/carveoutcosts/






More information about the sssd-devel mailing list