5. javascript文档字符串

而在python源代码中，我们只需要使用该指令包含一个模块docstring .. automodule:: mypythonmodule 因为没有包含javascript文件的本机指令，所以我们必须在doctring中明确定义javascript模块和函数。

5.1. 休息一代

pyjsrest 是一个小的实用程序，用于解析javascript文档并生成相应的重组文件，由sphinx用于生成HTML文档。此脚本将具有以下结构：

===========
filename.js
===========
.. module:: filename.js

我们使用 .. module:: 指令将javascript库注册为sphinx的python模块。这在模块索引中提供了一个条目。

在javascript文件中找到的docstring的内容将按照模块声明后的方式添加。医生不治疗。所有文档结构都将包含在docstring中，并符合以下规则。

5.2. 文档字符串结构

基本上，我们用restructuredtext docstring编写JavaScript，遵循与编写python代码相同的约定。

javascript文件中的doctring必须包含在标准的javascript注释符号中，从 /** 结束于 */ ，例如：

/**
 * My comment starts here.
 * This is the second line prefixed with a `*`.
 * ...
 * ...
 * All the follwing line will be prefixed with a `*` followed by a space.
 * ...
 * ...
 */

批注行前缀为 // 将被忽略。它们是为开发人员专用的源代码注释保留的。

5.3. Java脚本函数docstring

默认情况下， function 指令描述模块级函数。

5.3.1. function 指令

其目的是定义函数原型，例如：

.. function:: loadxhtml(url, data, reqtype, mode)

如果使用了任何名称空间，我们现在应该将其添加到原型中，直到定义适当的指令：

.. function:: jQuery.fn.loadxhtml(url, data, reqtype, mode)

5.3.2. 功能参数

我们将把函数参数定义为一个项目符号列表，在列表中，参数名称将被反引号括起来，然后是其描述。

javascript函数docstring示例：

.. function:: loadxhtml(url, data, reqtype, mode)

cubicweb loadxhtml plugin to make jquery handle xhtml response

fetches `url` and replaces this's content with the result

Its arguments are:

* `url`

* `mode`, how the replacement should be done (default is 'replace')
   Possible values are :
       - 'replace' to replace the node's content with the generated HTML
       - 'swap' to replace the node itself with the generated HTML
       - 'append' to append the generated HTML to the node's content

5.3.3. 可选参数规范

javascript函数处理函数签名中未列出的参数。在javascript代码中，将使用 /* ... */ .在docstring中，我们按照在python中定义的相同方式标记这些可选参数：

.. function:: asyncRemoteExec(fname, arg1=None, arg2=None)