All the procs inside the Tcl scripts must include some mandatory meta-comments. This applies to user procs (exported out of the namespace) as well as helper procs. The Xilinx Tcl Store linter generates error messages if the meta-comments are missing. The meta-comments for all the exported procs must have complete information. The helper procs however can have empty meta-comments, but the meta-comments must be declared.
The meta-comments provide information to the system such as a short description of what the procs are doing, some category information as well as the list of the command line options supported by the procs. The meta-comments must be included between the proc definition and before the first line of code. All of the meta-comments are mandatory.
The list of mandatory meta-comments is as follows:
- Summary
- Summary of what the proc is doing. This can be a multi-line summary. The summary is displayed inside the GUI as the proc short description.
- Argument Usage
- List of command line arguments in the proc. This meta-comment is used to build the Help system. Another section in this document describes the supported format.
- Return Value
- Use this meta-comment to specify the possible return values for the proc. This meta-comment is used to build the Help system.
- Categories
- List of categories the app belongs to. Use this meta-comment to specify
which categories in the Vivado Help system your app
should be listed under. In this meta-comment, "
Categories:" should be followed by a comma-separated list. By convention, the first category listed should always bexilinxtclstorefollowed by the app name.
Below is an example of meta-comments needed for a user proc.
proc ::tclapp::mycompany::template::my_command1 { args } {
# Summary: Multi-lines summary of
# what the proc is doing
# Argument Usage:
# [-verbose]: Verbose mode
# [-file <arg>]: Report file name
# [-append]: Append to file
# [-return_string]: Return report as string
# [-usage]: Usage information
# Return Value:
# return report if -return_string is used, otherwise 0. If any error occur TCL_ERROR
is returned
# Categories: xilinxtclstore, template
# The code for the proc starts below
…
}my_command1 that was created in the sub-namespace with its helper proc.
Below is an example of meta-comment for a helper proc. All the meta-comments are defined although they are empty:
proc ::tclapp::mycompany::template::my_command1::lshift {inputlist} {
# Summary :
# Argument Usage:
# Return Value:
# Categories:
# The code starts below
…
}To summarize, the rule is that all Tcl procs inside the scripts must include all the meta-comments. However, on the user procs exported from the namespace need to have detailed information.