Re: [PATCH] Add lib/parser.c kernel-doc

[Matthew Wilcox <willy@debian.org>]

On Sun, Nov 16, 2003 at 03:16:03AM -0500, Will Dyson wrote:
> +// associates an integer enumerator with a pattern string.

Please no C++ comments.

> -int match_int(substring_t *, int *result);
> -int match_octal(substring_t *, int *result);
> -int match_hex(substring_t *, int *result);
> -void match_strcpy(char *, substring_t *);
> -char *match_strdup(substring_t *);
> +int match_int(substring_t *s, int *result);
> +int match_octal(substring_t *s, int *result);
> +int match_hex(substring_t *s, int *result);
> +void match_strcpy(char *to, substring_t *s);
> +char *match_strdup(substring_t *s);

What value does this "s" add?  "result" is clearly useful documentation,
but "s" says "There is no good name for this variable"

> @@ -74,6 +85,20 @@
>  	}
>  }
>  
> +/**
> + * match_token: - Find a token (and optional args) in a string
> + * @s: the string to examine for token/argument pairs
> + * @table: match_table_t describing the set of allowed option tokens
> and the
> + * arguments that may be associated with them. Must be terminated with
> a
> + * &struct match_token who's pattern is set to the NULL pointer.

whose

> + * @args: array of %MAX_OPT_ARGS &substring_t elements. Used to return
> match
> + * locations.
> + *
> + * Description: Detects which if any of a set of token strings has been
> passed
> + * to it. Tokens can include up to MAX_OPT_ARGS instances of basic
> c-style
> + * format identifiers which will be taken into account when matching
> the
> + * tokens, and who's locations will be returned in the @args array.

ditto

> +/**
> + * match_strdup: - allocate a new c-string with the contents of a

Umm.  We're writing in C.  Just plain "string" is fine.

-- 
"It's not Hollywood.  War is real, war is primarily not about defeat or
victory, it is about death.  I've seen thousands and thousands of dead bodies.
Do you think I want to have an academic debate on this subject?" -- Robert Fisk