qapi: Make doc comments optional where we don't need them

==== Expression documentation ====

Each expression that isn't an include directive must be preceded by a

Each expression that isn't an include directive may be preceded by a

documentation block.  Such blocks are called expression documentation

blocks.

When documentation is required (see pragma 'doc-required'), expression

documentation blocks are mandatory.

The documentation block consists of a first line naming the

expression, an optional overview, a description of each argument (for

commands and events) or member (for structs, unions and alternates),

not used by any commands or events in the Client JSON Protocol, for

the side effect of generated C code used internally.

There are seven top-level expressions recognized by the parser:

'include', 'command', 'struct', 'enum', 'union', 'alternate', and

'event'.  There are several groups of types: simple types (a number of

built-in types, such as 'int' and 'str'; as well as enumerations),

complex types (structs and two flavors of unions), and alternate types

(a choice between other types).  The 'command' and 'event' expressions

can refer to existing types by name, or list an anonymous type as a

dictionary. Listing a type name inside an array refers to a

single-dimension array of that type; multi-dimension arrays are not

directly supported (although an array of a complex struct that

contains an array member is possible).

There are eight top-level expressions recognized by the parser:

'include', 'pragma', 'command', 'struct', 'enum', 'union',

'alternate', and 'event'.  There are several groups of types: simple

types (a number of built-in types, such as 'int' and 'str'; as well as

enumerations), complex types (structs and two flavors of unions), and

alternate types (a choice between other types).  The 'command' and

'event' expressions can refer to existing types by name, or list an

anonymous type as a dictionary. Listing a type name inside an array

refers to a single-dimension array of that type; multi-dimension

arrays are not directly supported (although an array of a complex

struct that contains an array member is possible).

All names must begin with a letter, and contain only ASCII letters,

digits, hyphen, and underscore.  There are two exceptions: enum values

  QType     QType      JSON string matching enum QType values

=== Includes ===

=== Include directives ===

Usage: { 'include': STRING }

prevent incomplete include files.

=== Pragma directives ===

Usage: { 'pragma': DICT }

The pragma directive lets you control optional generator behavior.

The dictionary's entries are pragma names and values.

Pragma's scope is currently the complete schema.  Setting the same

pragma to different values in parts of the schema doesn't work.

Pragma 'doc-required' takes a boolean value.  If true, documentation

is required.  Default is false.

=== Struct types ===

Usage: { 'struct': STRING, 'data': DICT, '*base': STRUCT-NAME }

#

##

{ 'pragma': { 'doc-required': true } }

# QAPI common definitions

{ 'include': 'qapi/common.json' }

#

##

{ 'pragma': { 'doc-required': true } }

##

# @guest-sync-delimited:

#

    'QType':    'QTYPE_QSTRING',

}

# Are documentation comments required?

doc_required = False

# Whitelist of commands allowed to return a non-dictionary

returns_whitelist = [

    # From QMP:

                                       "Value of 'include' must be a string")

                self._include(include, info, os.path.dirname(abs_fname),

                              previously_included)

            elif "pragma" in expr:

                if len(expr) != 1:

                    raise QAPISemError(info, "Invalid 'pragma' directive")

                pragma = expr['pragma']

                if not isinstance(pragma, dict):

                    raise QAPISemError(

                        info, "Value of 'pragma' must be a dictionary")

                for name, value in pragma.iteritems():

                    self._pragma(name, value, info)

            else:

                expr_elem = {'expr': expr,

                             'info': info}

        self.exprs.extend(exprs_include.exprs)

        self.docs.extend(exprs_include.docs)

    def _pragma(self, name, value, info):

        global doc_required

        if name == 'doc-required':

            if not isinstance(value, bool):

                raise QAPISemError(info,

                                   "Pragma 'doc-required' must be boolean")

            doc_required = value

        else:

            raise QAPISemError(info, "Unknown pragma '%s'" % name)

    def accept(self, skip_comment=True):

        while True:

            self.tok = self.src[self.cursor]

        expr = expr_elem['expr']

        info = expr_elem['info']

        if 'doc' not in expr_elem:

        if 'doc' not in expr_elem and doc_required:

            raise QAPISemError(info,

                               "Expression missing documentation comment")

        sys.exit(1)

    schema = qapi.QAPISchema(argv[1])

    if not qapi.doc_required:

        print >>sys.stderr, ("%s: need pragma 'doc-required' "

                             "to generate documentation" % argv[0])

    print texi(schema.docs)