5. Javascript docstrings

Whereas in Python source code we only need to include a module docstrings using the directive .. automodule:: mypythonmodule, we will have to explicitely define Javascript modules and functions in the doctrings since there is no native directive to include Javascript files.

5.1. Rest generation

pyjsrest is a small utility parsing Javascript doctrings and generating the corresponding Restructured file used by Sphinx to generate HTML documentation. This script will have the following structure:

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

We use the .. module:: directive to register a javascript library as a Python module for Sphinx. This provides an entry in the module index.

The contents of the docstring found in the javascript file will be added as is following the module declaration. No treatment will be done on the doctring. All the documentation structure will be in the docstrings and will comply with the following rules.

5.2. Docstring structure

Basically we document javascript with RestructuredText docstring following the same convention as documenting Python code.

The doctring in Javascript files must be contained in standard Javascript comment signs, starting with /** and ending with */, such as:

/**
 * 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.
 * ...
 * ...
 */

Comments line prefixed by // will be ignored. They are reserved for source code comments dedicated to developers.

5.3. Javscript functions docstring

By default, the function directive describes a module-level function.

5.3.1. function directive

Its purpose is to define the function prototype such as:

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

If any namespace is used, we should add it in the prototype for now, until we define an appropriate directive:

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

5.3.2. Function parameters

We will define function parameters as a bulleted list, where the parameter name will be backquoted and followed by its description.

Example of a javascript function 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. Optional parameter specification

Javascript functions handle arguments not listed in the function signature. In the javascript code, they will be flagged using /* ... */. In the docstring, we flag those optional arguments the same way we would define it in Python:

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