Question

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

假设我有一个名为runtest {ip_address test_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。

还有许多方法可以进行交互式文档编制，其中一些在the Tcler's Wiki中有描述;在我看来，该页面上提到的一些技术（连同@ slebetman的回答）会给你你想要的东西。（我认为使用单独的help命令会更容易，因为这会避免让帮助语法干扰命令，但那是你的调用。）

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

4 个答案: