diff --git a/Doc/Manual/Contents.html b/Doc/Manual/Contents.html index 22f6126de..06dd91ae6 100644 --- a/Doc/Manual/Contents.html +++ b/Doc/Manual/Contents.html @@ -1397,6 +1397,10 @@
  • Exceptions +
  • Documentation Features + diff --git a/Doc/Manual/Ocaml.html b/Doc/Manual/Ocaml.html index 62b5f926e..a3c60db02 100644 --- a/Doc/Manual/Ocaml.html +++ b/Doc/Manual/Ocaml.html @@ -53,6 +53,10 @@
  • Exceptions +
  • Documentation Features + @@ -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.

    +

    33.3 Documentation Features

    + + +

    +The features described in this section can be used to generate documentation +comments (colloquially referred to as "docstrings") that can be read by +OCamldoc. +

    + +

    33.3.1 Module docstring

    + + +

    +The first documentation comment of an mli file is the comment +associated with the entire module. SWIG supports this by setting an +option of the %module directive. For example: +

    + +
    +
    +%module(docstring="This is the example module's docstring") example
    +
    +
    + +

    +When you have more than just a line or so, you can retain the +readability of the %module directive by using a macro. For +example: +

    + +
    +
    +%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
    +
    +
    + diff --git a/Source/Modules/ocaml.cxx b/Source/Modules/ocaml.cxx index 99f2a98d7..1ab99705c 100644 --- a/Source/Modules/ocaml.cxx +++ b/Source/Modules/ocaml.cxx @@ -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");