[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