1 Javascript docstrings |
1 Javascript docstrings |
2 ===================== |
2 ===================== |
3 |
3 |
4 Whereas in Python source code we only need to include a module docstrings |
4 Whereas in Python source code we only need to include a module docstrings |
5 using the directive `.. automodule:: mypythonmodule`, we will have to |
5 using the directive `.. automodule:: mypythonmodule`, we will have to |
6 explicitely define Javascript modules and functions in the doctrings since |
6 explicitely define Javascript modules and functions in the doctrings since |
7 there is no native directive to include Javascript files. |
7 there is no native directive to include Javascript files. |
8 |
8 |
9 Rest generation |
9 Rest generation |
10 --------------- |
10 --------------- |
30 ------------------- |
30 ------------------- |
31 |
31 |
32 Basically we document javascript with RestructuredText docstring |
32 Basically we document javascript with RestructuredText docstring |
33 following the same convention as documenting Python code. |
33 following the same convention as documenting Python code. |
34 |
34 |
35 The doctring in Javascript files must be contained in standard |
35 The doctring in Javascript files must be contained in standard |
36 Javascript comment signs, starting with `/**` and ending with `*/`, |
36 Javascript comment signs, starting with `/**` and ending with `*/`, |
37 such as:: |
37 such as:: |
38 |
38 |
39 /** |
39 /** |
40 * My comment starts here. |
40 * My comment starts here. |
59 `function` directive |
59 `function` directive |
60 ~~~~~~~~~~~~~~~~~~~~ |
60 ~~~~~~~~~~~~~~~~~~~~ |
61 |
61 |
62 Its purpose is to define the function prototype such as:: |
62 Its purpose is to define the function prototype such as:: |
63 |
63 |
64 .. function:: loadxhtml(url, data, reqtype, mode) |
64 .. function:: loadxhtml(url, data, reqtype, mode) |
65 |
65 |
66 If any namespace is used, we should add it in the prototype for now, |
66 If any namespace is used, we should add it in the prototype for now, |
67 until we define an appropriate directive. |
67 until we define an appropriate directive:: |
68 :: |
68 |
69 .. function:: jQuery.fn.loadxhtml(url, data, reqtype, mode) |
69 .. function:: jQuery.fn.loadxhtml(url, data, reqtype, mode) |
70 |
70 |
71 Function parameters |
71 Function parameters |
72 ~~~~~~~~~~~~~~~~~~~ |
72 ~~~~~~~~~~~~~~~~~~~ |
73 |
73 |
74 We will define function parameters as a bulleted list, where the |
74 We will define function parameters as a bulleted list, where the |
75 parameter name will be backquoted and followed by its description. |
75 parameter name will be backquoted and followed by its description. |
76 |
76 |
77 Example of a javascript function docstring:: |
77 Example of a javascript function docstring:: |
78 |
78 |
79 .. function:: loadxhtml(url, data, reqtype, mode) |
79 .. function:: loadxhtml(url, data, reqtype, mode) |
80 |
80 |
81 cubicweb loadxhtml plugin to make jquery handle xhtml response |
81 cubicweb loadxhtml plugin to make jquery handle xhtml response |
82 |
82 |
83 fetches `url` and replaces this's content with the result |
83 fetches `url` and replaces this's content with the result |
84 |
84 |