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

[OCaml] Add support for the docstring option in the module directive

Browse source 
If given, the OCaml module will place the docstring at the very
beginning of the generated mli file, where it can be read by the
OCamldoc tool.

The implementation is based on the equivalent features in the Python
and Ruby modules.
This commit is contained in:
Zackery Spytz 2019-01-31 15:32:38 -07:00
commit 08029e6642
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>
<li><a href="Ocaml.html#Ocaml_nn31">Exceptions</a>
</ul>
<li><a href="Ocaml.html#Ocaml_nn32">Documentation Features</a>
<ul>
<li><a href="Ocaml.html#Ocaml_nn33">Module docstring</a>
</ul>
</ul>
</div>
<!-- INDEX -->

45
Doc/Manual/Ocaml.html
View file

@ -53,6 +53,10 @@
</ul>
<li><a href="#Ocaml_nn31">Exceptions</a>
</ul>
<li><a href="#Ocaml_nn32">Documentation Features</a>
<ul>
<li><a href="#Ocaml_nn33">Module docstring</a>
</ul>
</ul>
</div>
<!-- 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.
</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>
</html>

10
Source/Modules/ocaml.cxx
View file

@ -202,6 +202,7 @@ public:
* use %module(directors="1") modulename at the start of the
* interface file to enable director generation.
*/
String *mod_docstring = NULL;
{
Node *module = Getattr(n, "module");
if (module) {
@ -216,6 +217,7 @@ public:
if (Getattr(options, "sizeof")) {
generate_sizeof = 1;
}
mod_docstring = Getattr(options, "docstring");
}
}
}
@ -321,6 +323,14 @@ public:
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_mlibody, "val enum_to_int : c_enum_type -> c_obj -> Swig.c_obj\n");