1 Javascript docstrings |
|
2 ===================== |
|
3 |
|
4 Whereas in Python source code we only need to include a module docstrings |
|
5 using the directive `.. automodule:: mypythonmodule`, we will have to |
|
6 explicitely define Javascript modules and functions in the doctrings since |
|
7 there is no native directive to include Javascript files. |
|
8 |
|
9 Rest generation |
|
10 --------------- |
|
11 |
|
12 `pyjsrest` is a small utility parsing Javascript doctrings and generating the |
|
13 corresponding Restructured file used by Sphinx to generate HTML documentation. |
|
14 This script will have the following structure:: |
|
15 |
|
16 =========== |
|
17 filename.js |
|
18 =========== |
|
19 .. module:: filename.js |
|
20 |
|
21 We use the `.. module::` directive to register a javascript library |
|
22 as a Python module for Sphinx. This provides an entry in the module index. |
|
23 |
|
24 The contents of the docstring found in the javascript file will be added as is |
|
25 following the module declaration. No treatment will be done on the doctring. |
|
26 All the documentation structure will be in the docstrings and will comply |
|
27 with the following rules. |
|
28 |
|
29 Docstring structure |
|
30 ------------------- |
|
31 |
|
32 Basically we document javascript with RestructuredText docstring |
|
33 following the same convention as documenting Python code. |
|
34 |
|
35 The doctring in Javascript files must be contained in standard |
|
36 Javascript comment signs, starting with `/**` and ending with `*/`, |
|
37 such as:: |
|
38 |
|
39 /** |
|
40 * My comment starts here. |
|
41 * This is the second line prefixed with a `*`. |
|
42 * ... |
|
43 * ... |
|
44 * All the follwing line will be prefixed with a `*` followed by a space. |
|
45 * ... |
|
46 * ... |
|
47 */ |
|
48 |
|
49 |
|
50 Comments line prefixed by `//` will be ignored. They are reserved for source |
|
51 code comments dedicated to developers. |
|
52 |
|
53 |
|
54 Javscript functions docstring |
|
55 ----------------------------- |
|
56 |
|
57 By default, the `function` directive describes a module-level function. |
|
58 |
|
59 `function` directive |
|
60 ~~~~~~~~~~~~~~~~~~~~ |
|
61 |
|
62 Its purpose is to define the function prototype such as:: |
|
63 |
|
64 .. function:: loadxhtml(url, data, reqtype, mode) |
|
65 |
|
66 If any namespace is used, we should add it in the prototype for now, |
|
67 until we define an appropriate directive:: |
|
68 |
|
69 .. function:: jQuery.fn.loadxhtml(url, data, reqtype, mode) |
|
70 |
|
71 Function parameters |
|
72 ~~~~~~~~~~~~~~~~~~~ |
|
73 |
|
74 We will define function parameters as a bulleted list, where the |
|
75 parameter name will be backquoted and followed by its description. |
|
76 |
|
77 Example of a javascript function docstring:: |
|
78 |
|
79 .. function:: loadxhtml(url, data, reqtype, mode) |
|
80 |
|
81 cubicweb loadxhtml plugin to make jquery handle xhtml response |
|
82 |
|
83 fetches `url` and replaces this's content with the result |
|
84 |
|
85 Its arguments are: |
|
86 |
|
87 * `url` |
|
88 |
|
89 * `mode`, how the replacement should be done (default is 'replace') |
|
90 Possible values are : |
|
91 - 'replace' to replace the node's content with the generated HTML |
|
92 - 'swap' to replace the node itself with the generated HTML |
|
93 - 'append' to append the generated HTML to the node's content |
|
94 |
|
95 |
|
96 Optional parameter specification |
|
97 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
98 |
|
99 Javascript functions handle arguments not listed in the function signature. |
|
100 In the javascript code, they will be flagged using `/* ... */`. In the docstring, |
|
101 we flag those optional arguments the same way we would define it in |
|
102 Python:: |
|
103 |
|
104 .. function:: asyncRemoteExec(fname, arg1=None, arg2=None) |
|
105 |
|
106 |
|