Meta-Comment Argument Usage - 2024.1 English

This is the most complex of the meta-comments. There should be one line for each mandatory or optional argument supported by your proc. Optional arguments should be enclosed within []. Arguments that are accompanied by a value must be followed by the literal text '<arg>' (without quotes), indicating to the user where the value should be placed. The summary should explain what are the valid values that a user could use. You can also specify a default value, which is a value that is assumed if the user does not specify the given optional argument. You can also have optional arguments that do not take any value (these are often referred to as "flags"). A flag's presence on the command line implies a value of true, indicating that some optional action should be taken by the app. An exception to this rule is if the name of the flag is prefixed with "no_" (for example, -no_cleanup), in which case a value of false is implied, indicating that the app does not take some action, which by default it normally performs.

You can also specify positional arguments. A positional argument is one for which a value is specified and that has no corresponding flag (for example, -arg1).

For example, the following meta-comment:

  # Argument Usage:
  # timingPath : mandatory name
  # [-append]: optional flag
  # -cell <arg>: mandatory argument with no default value
  # [-template <arg> = stub]: optional argument with a default value. The default 
value is: stub

Results in the following Help message:

Syntax: 
mycompany::template::mycommand [-append] -cell <arg> [-template <arg>]
                                     [-quiet] [-verbose] <timingPath> <-name>
Returns: 
template in the case of -return_string, otherwise 0 TCL_ERROR if error
Usage: 
  Name     Description
  -------------------------
  [-append]   optional flag
                Default: 0
  -cell     mandatory argument with no default value
  [-template]  optional argument with a default value. The default value is: 
                stub
                Default: stub
  [-quiet]   Ignore command errors
  [-verbose]  Suspend message limits during command execution
  <timingPath> mandatory

The actual processing of the command line arguments has to be programmatically done inside the proc.