Hi Heinrich,

On Sun, Jul 29, 2018 at 12:08 PM, Heinrich Schuchardt xypron.glpk@gmx.de wrote:

Describe the interface of environment variable callback functions.

Signed-off-by: Heinrich Schuchardt xypron.glpk@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