jsdoc_在Windows上运行JSDoc

最新推荐文章于 2022-07-26 19:05:55 发布

cunbei2644

最新推荐文章于 2022-07-26 19:05:55 发布

阅读量248

点赞数

文章标签： python java linux php js ViewUI

原文链接：https://www.phpied.com/running-jsdoc-on-windows/

版权

jsdoc

动机(Motivation)

As your JavaScript grows bigger, it becomes harder to manage. A way to make it more manageable is by documenting properly what each function/method does, what type of parameters it accepts and what it returns. The laziest way do document is to use in-code comments in JavaDoc style and then to run a script to parse those comments and to produce nicely formatted documentation.

随着您JavaScript变得越来越大，它变得越来越难以管理。使它更易于管理的一种方法是正确记录每个函数/方法的功能，接受的参数类型以及返回的参数。编写文档最懒惰的方法是使用JavaDoc风格的代码内注释，然后运行脚本来解析这些注释并生成格式正确的文档。

Java-devs have JavaDoc and have been using it successfully for years. PHP has phpDoc which is also widely used for example by the PEAR project (example). Now JavaScript has the tool to use the same idea. The tool is JSDoc.

Java开发人员拥有JavaDoc，并且已经成功使用了多年。 PHP具有phpDoc ，它也被PEAR项目(例如)广泛使用。现在，JavaScript具有使用相同想法的工具。该工具是JSDoc 。

您需要什么才能使用JSDoc？ (What you need in order to use JSDoc?)

Perl - as the JSDoc tool is written in Perl
Perl-JSDoc工具是用Perl编写的
CPAN - JSDoc requires some collection Perl libraries
CPAN-JSDoc需要一些Perl库集合
JSDoc - the tool itself
JSDoc-工具本身

安装Perl(Installing Perl)

To run Perl on Windows you need ActivePerl.

要在Windows上运行Perl，您需要ActivePerl。

Visit ActiveState's downloads page.
访问ActiveState的下载页面。
Click "Download ActivePerl"
单击“下载ActivePerl”
(optionally) Provide your contact info
(可选)提供您的联系信息
Download the Windows package (currently ActivePerl-5.8.7.815-MSWin32-x86-211909.zip, 12.9MB)
下载Windows软件包(当前为ActivePerl-5.8.7.815-MSWin32-x86-211909.zip，12.9MB)
Uncompress the downloaded archive
解压缩下载的档案
Make sure you have 80MBs of free space, run installer.bat and follow the instructions
确保您有80MB的可用空间，运行installer.bat并按照说明进行操作
Point the installer to let's say C:\perl
将安装程序指向C:\perl
Answer "y" to the question "Add the Perl\bin directory to the PATH? [y]"
对问题“将Perl \ bin目录添加到PATH？[y]”回答“ y”
(grab a coffee, the installer takes some time)
(喝咖啡，安装程序需要一些时间)

At the end, in order to validate that all was installed OK and the path to Perl was set in your environment, open a console window (Start->Run->'cmd') and type (in any directory):

最后，为了验证所有程序是否都已正确安装并且在您的环境中设置了Perl的路径，请打开一个控制台窗口(开始->运行->'cmd')，然后键入(在任何目录中)：

perl -v

This should print Perl version information. If it doesn't, you might need to restart your PC and/or set the path to Perl manually.

这应该打印Perl版本信息。如果没有，您可能需要重新启动PC和/或手动将路径设置为Perl。

CPAN (CPAN)

Luckily, ActivePerl installs CPAN as well, together with the PPM utility (Perl Package Manager) that you can use to add/remove CPAN libraries. One library that JSDoc requires and doesn't come with the default ActivePerl install is HTML-Templates. To install it, open a console window and type:

幸运的是，ActivePerl还将安装CPAN以及PPM实用程序(Perl程序包管理器)，您可以使用它来添加/删除CPAN库。 JSDoc要求且不包含默认ActivePerl安装的一个库是HTML-Templates。要安装它，请打开控制台窗口，然后键入：

ppm

The PPM prompt comes up.

出现PPM提示。

Type:

类型：

PPM> install HTML-Template

and finally, quit:

最后，退出：

PPM> q

JSDoc(JSDoc)

Download the latest JSDoc package and simply uncompress it somewhere, for example c:\JSDoc

下载最新的JSDoc软件包，然后只需将其解压缩即可，例如c:\JSDoc

准备好，稳定，出发！ (Ready, steady, go!)

JSDoc comes with an example script that shows you examples of how to use the syntax. To make sure all is installed and running smoothly, try to run the documentor tool on the test.js script.

JSDoc附带了一个示例脚本，该脚本向您显示如何使用语法的示例。为确保所有组件均已安装并正常运行，请尝试在test.js脚本上运行documentor工具。

JSDoc is a command line tool and the most basic example is to navigate to the directory where you installed JSDoc (in my case - c:\JSDoc) and to type:

JSDoc是一个命令行工具，最基本的示例是导航到安装JSDoc的目录(在我的情况下为c:\JSDoc )并键入：

perl jsdoc.pl test.js

This will parse the comments in test.js script found in the same directory and will produce a bunch of html documents in folder c:\JSDoc\js_docs_out. You can load the index.html found in this directory to admire the result.

这将解析在同一目录中找到的test.js脚本中的注释，并将在文件夹c:\JSDoc\js_docs_out生成一堆html文档。您可以加载在此目录中找到的index.html以欣赏结果。

一些选择 (Some options)

If you want to create the documentation in a different folder, use the -d option, like:

如果要在其他文件夹中创建文档，请使用-d选项，例如：

perl jsdoc.pl test.js -d=c:\some\folder

You can run JSDoc from any directory, let's say you're in c:\some\weird\place. You can still execute the documentor, feed it a script that's located anywhere and have the output documentation where you want it.

您可以从任何目录运行JSDoc，假设您位于c:\some\weird\place 。您仍然可以执行文档编制器，向它提供脚本，该脚本位于任何地方，并在您需要的位置提供输出文档。

perl c:\JSDoc\jsdoc.pl c:\JSdoc\test.js -d=c:\jsdoctest

Executing with -h will give you hints about the other available options:

使用-h执行将为您提供有关其他可用选项的提示：

perl c:\JSDoc\jsdoc.pl -h

语法说明 (A note on syntax)

In order to feed the documentor you need to put comments in your code, before a method/function, like this:

为了提供给文档编制者，您需要在方法/函数之前在代码中添加注释，如下所示：

/**
*
*/

Within the comments you put description and some tags. For example:

在注释中放入描述和一些标签。例如：

/**
* This is a function that calculates the length of a full name
* based on given first and last names. The method is
* not really implemented yet, but this is just a beta.
* @param {string} first_name First name
* @param {string} last_name Last name
* @return {int} The number of letters in a name
*/
function getFullNameLength(first_name, last_name) {
    //...
}

Here's the result documentation produced by JSDoc when parsing this simple function placed in a file.

这是JSDoc解析放在文件中的此简单函数时生成的结果文档。

一些特殊标签 (Some special tags)

In JavaScript there's no inheritance, but you can code to achieve the same result. In order for the JSDoc to show in the documentation that a class inherits another class, you put @extends.

在JavaScript中没有继承，但是您可以编码以获得相同的结果。为了使JSDoc在文档中显示一个类继承了另一个类，请放置@extends 。

To define a method as a private method you use @private. Private methods are not included in the documentation unless you explicitly use -p option when running JSDoc.

要将方法定义为私有方法，请使用@private 。除非您在运行JSDoc时显式使用-p选项，否则私有方法不包含在文档中。