Declaration

Description

Declaring environment parameters used in your code with automatic documentation.

For declaring variables reflecting environment settings, the following macros should be used, and the variables should be declared globally. This way, automatic tools can generate a documentation of the environment parameters. The macros take care of properly initializing the variables in 'EnvInit', the user does not need to call 'EnvGet...' for these variables. If this is not possible (e.g. because the key is variable or the type does not match any of the standard types), the macro 'ENV_PARA_SPECIAL' must be inserted to inform the documentation tools. 'ENV_PARA_SPECIAL' may be followed by (custom) variable declaration in the same line Each macro invocation must be followed by a comment with the parameter documentation in the following format:

ENV_PARA_... (...)
 / * Short description (max. ~40 chars, no trailing period)
   *
   * Optional long description, optionally covering multiple lines or empty lines.
   * Only the last line must not be empty, and there must be exactly one empty
   * line between the short and the long description.
   *
   * Formatting can be done with LaTeX syntax.
   * /

Details on formatting options can be found in the Home2L Book.

Note: Persistent variables ("var.*" domain) cannot be initialized this way. They must be declared via 'ENV_PARA_SPECIAL'.

Collaboration diagram for Declaration:

Variables with standard types ...
#define	ENV_PARA_STRING(key, varName, varDefault)   const char *varName = varDefault; CEnvPara varName##PreInit (key, eptString, &varName); const char *varName##Key = key;
#define	ENV_PARA_PATH(key, varName, varDefault)   const char *varName = varDefault; CEnvPara varName##PreInit (key, eptPath, &varName); const char *varName##Key = key;
	Path can be made absolute before first use by calling EnvGetPath (<varName>Key, &<varName>, [<base path>] ) afterwards.
#define	ENV_PARA_INT(key, varName, varDefault)   int varName = varDefault; CEnvPara varName##PreInit (key, eptInt, &varName); const char *varName##Key = key;
#define	ENV_PARA_FLOAT(key, varName, varDefault)   float varName = varDefault; CEnvPara varName##PreInit (key, eptFloat, &varName); const char *varName##Key = key;
#define	ENV_PARA_BOOL(key, varName, varDefault)   bool varName = varDefault; CEnvPara varName##PreInit (key, eptBool, &varName); const char *varName##Key = key;

Variables for special cases ...
such as free types, manual initialization or read-only variables.
#define	ENV_PARA_VAR(key, varType, varName, varDefault)   varType varName = varDefault; const char *varName##Key = key;

Keys without a variable ...
The macro just defines a key name as a constant variable.
#define	ENV_PARA_NOVAR(key, varType, varName, varDefault)   const char *varName##Key = key;
	Argument 'varType' is used for automatic documentation.

Groups of variables ...
such as patterned variables like doorman.<PHONE>.register.
#define	ENV_PARA_SPECIAL(keyPattern, varType, varDefault)
	Arguments 'varType' and 'varDefault' are used for automatic documentation.