Require documentation on cretonne public items.

lib/cretonne/meta/cretonne/__init__.py

@@ -707,6 +707,11 @@ class InstructionFormat(object):
             self.members.append(member)
             yield k
 
+    def __str__(self):
+        args = ', '.join('{}: {}'.format(m, k) if m else str(k)
+                         for m, k in zip(self.members, self.kinds))
+        return '{}({})'.format(self.name, args)
+
     def __getattr__(self, attr):
         # type: (str) -> FormatField
         """

lib/cretonne/meta/gen_instr.py

@@ -19,6 +19,7 @@ def gen_formats(fmt):
     fmt.line('#[derive(Copy, Clone, PartialEq, Eq, Debug)]')
     with fmt.indented('pub enum InstructionFormat {', '}'):
         for f in cretonne.InstructionFormat.all_formats:
+            fmt.doc_comment(str(f))
             fmt.line(f.name + ',')
     fmt.line()
 
@@ -172,6 +173,7 @@ def gen_opcodes(groups, fmt):
     fmt.line('#[derive(Copy, Clone, PartialEq, Eq, Debug)]')
     instrs = []
     with fmt.indented('pub enum Opcode {', '}'):
+        fmt.doc_comment('An invalid opcode.')
         fmt.line('NotAnOpcode,')
         for g in groups:
             for i in g.instructions:
@@ -364,6 +366,7 @@ def gen_format_constructor(iform, fmt):
     proto = '{}({})'.format(iform.name, ', '.join(args))
     proto += " -> (Inst, &'f mut DataFlowGraph)"
 
+    fmt.doc_comment(str(iform))
     fmt.line('#[allow(non_snake_case)]')
     with fmt.indented('fn {} {{'.format(proto), '}'):
         # Generate the instruction data.

lib/cretonne/meta/gen_settings.py

@@ -16,10 +16,12 @@ def gen_enum_types(sgrp, fmt):
         if not isinstance(setting, EnumSetting):
             continue
         ty = camel_case(setting.name)
+        fmt.doc_comment('Values for {}.'.format(setting))
         fmt.line('#[derive(Debug, PartialEq, Eq)]')
-        fmt.line(
-                'pub enum {} {{ {} }}'
-                .format(ty, ", ".join(camel_case(v) for v in setting.values)))
+        with fmt.indented('pub enum {} {{'.format(ty), '}'):
+            for v in setting.values:
+                fmt.doc_comment('`{}`.'.format(v))
+                fmt.line(camel_case(v) + ',')
 
 
 def gen_getter(setting, sgrp, fmt):
@@ -70,7 +72,7 @@ def gen_getters(sgrp, fmt):
     """
     fmt.doc_comment("User-defined settings.")
     with fmt.indented('impl Flags {', '}'):
-        # Dynamic numbered predicate getter.
+        fmt.doc_comment('Dynamic numbered predicate getter.')
         with fmt.indented(
                 'pub fn numbered_predicate(&self, p: usize) -> bool {', '}'):
             fmt.line(
@@ -187,6 +189,7 @@ def gen_constructor(sgrp, parent, fmt):
         if sgrp.parent:
             p = sgrp.parent
             args = '{}: &{}::Flags, {}'.format(p.name, p.qual_mod, args)
+        fmt.doc_comment('Create flags {} settings group.'.format(sgrp.name))
         with fmt.indented(
                 'pub fn new({}) -> Flags {{'.format(args), '}'):
             fmt.line('let bvec = builder.state_for("{}");'.format(sgrp.name))