如何为 SAHI 脚本生成 Javadoc 样式文档？答案

【问题标题】：How do I generate Javadoc Style Documentation for SAHI scripts?如何为 SAHI 脚本生成 Javadoc 样式文档？
【发布时间】：2016-03-16 20:35:15
【问题描述】：

我使用 sahi-script 编写了所有测试，因为这是使用此工具的推荐方式： https://sahipro.com/docs/using-sahi/recommended-usage.html#Language%20Recommendation

现在我需要编写 Javadoc 样式的文档，并尝试运行 Javadoc。我想也许是因为：“JS 版本还可以调用和重用任何 Java 代码或库，因此您可以拥有 JS 的简单性，但也可以在需要时使用 Java 的强大功能。”它会起作用，但我得到了这个：

>javadoc baum.sah
>Loading source files for package baum.sah...
>javadoc warning: No source files for package baum.sah
>Constructing Javadoc information...
>javadoc warning: No source files for package baum.sah
>javadoc error: No public or protected classes found to document.
>1 error
>2 warnings

我的问题是：

1.) 有什么方法可以得到 Javadoc 风格的文档，而不必用 Java 重写所有 SAHI 脚本代码？

2.) 如果是，你是如何一步一步做到的？

【问题讨论】：

标签： javascript java documentation javadoc sahi

【解决方案1】：

Sahi 代码是用 Javascript 编写的，是 javascript 的包装器。您可以使用 jsdoc3 (https://github.com/jsdoc3/jsdoc) 为您的 sahi 脚本生成 javadoc 样式文档。如果您签入旧版本的 Sahi（大约 5.2），则会有一个名为 apis.sah 的文件，其中存在 jsdoc3 样式文档。

【讨论】：

我的家用电脑“Windows 7”上有 SAHI Open Source 5，那里的 API 文件中唯一的文档是 @return 注释，仅此而已。在工作中，我使用“Ubuntu 14”系统和 SAHI Pro 6，我需要检查那里的 API 以在下周一确认您的答案。
我指的是专业版
在 .sah 文件上运行 jsdoc-toolkit 2.4.0 不起作用，生成的 html 文件中没有内容
我接受了你的回答，因为它引导我实现了我的目标，我在下面的答案中记录了我的步骤

【解决方案2】：

这是我的逐步回答，因为运行 jsdoc-toolkit 对 .sah 文件不起作用。前提是你已经下载并安装了java:http://www.java.com/de/download/windows_xpi.jsp

1.)convert .sah-files into .js-files

Sahi 的 .sah 文件可以转换为 .js 文件：https://sahipro.com/docs/faq/eclipse-integration.html

2.)download a js-toolkit and unzip it

您最好遵循这些简单的说明：https://code.google.com/p/jsdoc-toolkit/wiki/InstallJsdoc

我不建议在 Windows 7 上下载 node.js 并使用 npm 安装 jsdoc，因为你会像我一样遇到很多问题：https://github.com/npm/npm/wiki/Troubleshooting#upgrading-on-windows

3.)open a cmd and run the command where you unzipped the jsdoc-toolkit

path_where_unzipped_folder\jsdoc_toolkit-2.4.0\jsdoc-toolkit>java -jar jsrun.jar app/run.js your_path_to_file\anyfile.js -t=templates\jsdoc 


4.)look up your generated documentation html files here:

path_where_unzipped_folder\jsdoc_toolkit-2.4.0\jsdoc-toolkit\out\jsdoc

在这里查看 JSDoc 文档用法：http://usejsdoc.org/index.html

【讨论】：