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(a)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