[U-Boot] [PATCH 1/1] README: U_BOOT_ENV_CALLBACK functions

[Sam Protsenko]

Hi Heinrich,

On Sun, Jul 29, 2018 at 12:08 PM, Heinrich Schuchardt
<xypron.glpk at gmx.de> wrote:
> Describe the interface of environment variable callback functions.
>
> Signed-off-by: Heinrich Schuchardt <xypron.glpk at gmx.de>
> ---
>  README | 11 +++++++++++
>  1 file changed, 11 insertions(+)
>
> diff --git a/README b/README
> index aee0f7371c4..179d6d74a4a 100644
> --- a/README
> +++ b/README
> @@ -3943,6 +3943,17 @@ If CONFIG_REGEX is defined, the variable_name above is evaluated as a
>  regular expression. This allows multiple variables to be connected to
>  the same callback without explicitly listing them all out.
>
> +The signature of the callback functions is:
> +
> +    int callback(const char *name, const char *value, enum env_op op, int flags)
> +
> +* name - changed environment variable
> +* value - new value of the environment variable
> +* op - operation (create, overwrite, or delete)
> +* flags - attributes of the environment variable change, see flags H_* in
> +  include/search.h
> +
> +The return value is 0 if the variable change is accepted and 1 otherwise.
>

This description looks more like Doxygen comment to me than a
documentation. So I wonder if it makes sense to move it into "struct
env_clbk_tbl" (include/env_callback.h), as Doxygen comment for
(*callback) field documentation. Or e.g. extract callback type from
that struct (use "typedef callback_t" or something), and document it
instead. Then a reference to that doc can be added to
U_BOOT_ENV_CALLBACK to make it easier for developers to find it while
coding.

The motivation is:
 1. Callback signature may change in future, and it's easy to forget
to update README accordingly. Hence it's better to keep function
documentation in code
 2. Developer is usually looks in code rather that to README while
coding, so it may be more helpful to keep function documentation in
code as well

Does it make sense?

Thanks.

>  Command Line Parsing:
>  =====================
> --
> 2.18.0
>