jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge branch 'ZackerySpytz-OCaml-module-docstring'

Browse source 
* ZackerySpytz-OCaml-module-docstring:
  [OCaml] Add support for the docstring option in the module directive
This commit is contained in:
William S Fulton 2019-02-09 22:02:21 +00:00
commit 5249dfefc5
3 changed files with 59 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

4
Doc/Manual/Contents.html
View file

@ -1397,6 +1397,10 @@
</ul> </ul>
<li><a href="Ocaml.html#Ocaml_nn31">Exceptions</a> <li><a href="Ocaml.html#Ocaml_nn31">Exceptions</a>
</ul> </ul>
<li><a href="Ocaml.html#Ocaml_nn32">Documentation Features</a>
<ul>
<li><a href="Ocaml.html#Ocaml_nn33">Module docstring</a>
</ul>
</ul> </ul>
</div> </div>
<!-- INDEX --> <!-- INDEX -->

45
Doc/Manual/Ocaml.html
View file

@ -53,6 +53,10 @@
</ul> </ul>
<li><a href="#Ocaml_nn31">Exceptions</a> <li><a href="#Ocaml_nn31">Exceptions</a>
</ul> </ul>
<li><a href="#Ocaml_nn32">Documentation Features</a>
<ul>
<li><a href="#Ocaml_nn33">Module docstring</a>
</ul>
</ul> </ul>
</div> </div>
<!-- INDEX --> <!-- INDEX -->
@ -992,5 +996,46 @@ but not too useful example is provided by the throw_exception testcase in
Examples/test-suite. You can provide your own exceptions, too. Examples/test-suite. You can provide your own exceptions, too.
</p> </p>
<H2><a name="Ocaml_nn32">33.3 Documentation Features</a></H2>
<p>
The features described in this section can be used to generate documentation
comments (colloquially referred to as "docstrings") that can be read by
<a href="https://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html">OCamldoc</a>.
</p>
<H3><a name="Ocaml_nn33">33.3.1 Module docstring</a></H3>
<p>
The first documentation comment of an <tt>mli</tt> file is the comment
associated with the entire module. SWIG supports this by setting an
option of the <tt>%module</tt> directive. For example:
</p>
<div class="code">
<pre>
%module(docstring="This is the example module's docstring") example
</pre>
</div>
<p>
When you have more than just a line or so, you can retain the
readability of the <tt>%module</tt> directive by using a macro. For
example:
</p>
<div class="code">
<pre>
%define DOCSTRING
"The `XmlResource` class allows program resources defining menus,
controls on a panel, etc. to be loaded from an XML file."
%enddef
%module(docstring=DOCSTRING) xrc
</pre>
</div>
</body> </body>
</html> </html>

10
Source/Modules/ocaml.cxx
View file

@ -202,6 +202,7 @@ public:
* use %module(directors="1") modulename at the start of the * use %module(directors="1") modulename at the start of the
* interface file to enable director generation. * interface file to enable director generation.
*/ */
String *mod_docstring = NULL;
{ {
Node *module = Getattr(n, "module"); Node *module = Getattr(n, "module");
if (module) { if (module) {
@ -216,6 +217,7 @@ public:
if (Getattr(options, "sizeof")) { if (Getattr(options, "sizeof")) {
generate_sizeof = 1; generate_sizeof = 1;
} }
mod_docstring = Getattr(options, "docstring");
} }
} }
} }
@ -321,6 +323,14 @@ public:
Language::top(n); Language::top(n);
if (mod_docstring) {
if (Len(mod_docstring)) {
Printv(f_mliout, "(** ", mod_docstring, " *)\n", NIL);
}
Delete(mod_docstring);
mod_docstring = NULL;
}
Printf(f_enum_to_int, ") | _ -> (C_int (get_int v))\n" "let _ = Callback.register \"%s_enum_to_int\" enum_to_int\n", module); Printf(f_enum_to_int, ") | _ -> (C_int (get_int v))\n" "let _ = Callback.register \"%s_enum_to_int\" enum_to_int\n", module);
Printf(f_mlibody, "val enum_to_int : c_enum_type -> c_obj -> Swig.c_obj\n"); Printf(f_mlibody, "val enum_to_int : c_enum_type -> c_obj -> Swig.c_obj\n");