diff mbox series

[v3,05/12] tools/ocaml: abi-check: Add comments

Message ID 20190910120207.10358-6-ian.jackson@eu.citrix.com (mailing list archive)
State New, archived
Headers show
Series ocaml abi fixes | expand

Commit Message

Ian Jackson Sept. 10, 2019, 12:02 p.m. UTC 
Provide interface documentation for this script.

Explain why we check .ml not .mli.

Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
Signed-off-by: Ian Jackson <ian.jackson@eu.citrix.com>
---
 tools/ocaml/libs/xc/abi-check | 15 +++++++++++++++
 1 file changed, 15 insertions(+)
diff mbox series

Patch

diff --git a/tools/ocaml/libs/xc/abi-check b/tools/ocaml/libs/xc/abi-check
index c987cd8454..ccc35e79e9 100755
--- a/tools/ocaml/libs/xc/abi-check
+++ b/tools/ocaml/libs/xc/abi-check
@@ -5,6 +5,13 @@  use Data::Dumper;
 
 our %enums;
 
+# Usage: abi-check C-file Ocaml-file
+# Writes out a BUILD_BUG_ON() list to be included back into C.
+#
+# Ocaml-file should be the .ml file.  The ocaml compiler will check
+# that any declarations in a .mli correspond.  We check the .ml
+# rather than the .mli in case there are private types in future.
+
 @ARGV == 2 or die;
 our ($c, $o) = @ARGV;
 
@@ -13,6 +20,14 @@  open STDIN, "<", $c or die $!;
 our $cline = -1;
 our $ei;
 
+# Parse the C file looking for calls to:
+#   c_bitmap_to_ocaml_list()
+#
+# followed by anotations of the following form:
+#   /* ! OType OPrefix Mangle */
+#   /* ! CPrefix CFinal CFinalHow */
+#
+# The function definitions use /* ! */ which simply skips that instance.
 while (<>) {
     if ($cline == -1) {
         if (m/c_bitmap_to_ocaml_list/) {