为TCL中的用户定义函数添加帮助

Question

如何为TCL 中的用户定义函数添加某种帮助

假设我有一个名为runtest{ip_addresstest_time}的函数，如何描述TCL_shell中的测试或程序？

如果用户在TCL shell中键入function_name--help，用户应该能够知道函数的作用和参数，我如何向用户指定信息。

我该怎么做？

Answer 1

虽然它确实不是语言的一部分，但实现将此功能添加到预先存在的函数中是相当容易的。唯一需要注意的是，函数不能将字符串--help作为有效参数，因为该参数将触发该功能。

这里有一个简单的实现：

# Lets call the feature "document". As in, add documentation:
proc document {procname text} {
  rename $procname __$procname
  proc $procname args [string map [list %TEXT% $text %PROC% $procname] {
    if {$args == "--help"} {
      puts {%TEXT%}
    } else {
      set script [linsert $args 0 __%PROC%]
      return [uplevel 1 $script]
    }
  }]
}

这样做的目的是覆盖该函数（通过重命名，然后声明另一个同名函数），并查看是否使用参数--help调用该函数。如果是，则打印文档，否则执行原始函数。只是要注意不要在同一个函数上调用两次（不过可以对其进行修改以使其工作）。

所以你可以做这样的事情：

proc foo {} {puts 2}
document foo {Prints the number 2.}

现在，如果你打电话：

foo --help

它会输出：

Prints the number 2.

Answer 2

您不必接触现有程序：

proc help {procname} {
  puts $::helptext($procname)
}
proc addhelp {procname text} {
  set ::helptext($procname) $text
}
addhelp foo "this is the help text for procedure foo"
help foo

Answer 3

如果不重新定义proc命令，就无法执行。也就是说，这种功能并没有内置在语言中，但如果你愿意的话，可以添加。

我会注意到，如果可能的话，你自己添加这种能力可能已经超出了值得做的困难范围，尤其是对于不太熟悉这种语言的人来说。话虽如此，您可以在tclers wiki中查看预先存在的实现。

Answer 4

我倾向于将帮助放在一个单独的文件中（例如，HTML），这样我就可以在另一个窗口中浏览它。有很多方法可以做到这一点，同时仍然保留文档和代码，例如通过doxygen。

还有许多交互文档的方法，其中一些方法在Tcler的Wiki中进行了描述；在我看来，该页面上提到的一些技巧（以及@slebetman的答案）会给你带来你想要的。（我认为有一个单独的help命令会更容易，因为这样可以避免帮助语法干扰命令，但这是你的选择。）