Revert some parser changes that had allowed the intro section to start on the same line as the definition name. If we go this route, the changes need to be back-squashed into earlier commits and the qapi-code-gen.rst documentation needs to be rewritten and reworded a little bit.
Signed-off-by: John Snow <[email protected]> --- docs/sphinx/qapidoc.py | 5 +- qapi/accelerator.json | 18 +++-- qapi/acpi-hest.json | 5 +- qapi/acpi.json | 13 ++-- qapi/audio.json | 88 ++++++++++++++++--------- scripts/qapi/parser.py | 12 +--- tests/qapi-schema/doc-missing-colon.err | 2 +- 7 files changed, 86 insertions(+), 57 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 6b8e4ecd76a..985954164b0 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -156,8 +156,9 @@ def add_lines( lines = content.splitlines(True) if dedent: - txt = "".join(lines[1:]) - lines[1:] = textwrap.dedent(txt).splitlines(True) + lines = textwrap.dedent(content).splitlines(True) + else: + lines = content.splitlines(True) for i, line in enumerate(lines): self.add_line_raw(line, info.fname, info.line + i) diff --git a/qapi/accelerator.json b/qapi/accelerator.json index 71047538ee1..05dbef51c5d 100644 --- a/qapi/accelerator.json +++ b/qapi/accelerator.json @@ -12,7 +12,8 @@ { 'include': 'common.json' } ## -# @KvmInfo: Information about support for KVM acceleration +# @KvmInfo: +# Information about support for KVM acceleration # # @enabled: true if KVM acceleration is active # @@ -23,7 +24,8 @@ { 'struct': 'KvmInfo', 'data': {'enabled': 'bool', 'present': 'bool'} } ## -# @query-kvm: Return information about KVM acceleration +# @query-kvm: +# Return information about KVM acceleration # # Since: 0.14 # @@ -35,7 +37,8 @@ { 'command': 'query-kvm', 'returns': 'KvmInfo' } ## -# @x-accel-stats: Query accelerator statistics +# @x-accel-stats: +# Query accelerator statistics # # Features: # @@ -50,7 +53,8 @@ 'features': [ 'unstable' ] } ## -# @Accelerator: Information about support for MSHV acceleration +# @Accelerator: +# Information about support for MSHV acceleration # # @hvf: Apple Hypervisor.framework # @@ -73,7 +77,8 @@ { 'enum': 'Accelerator', 'data': ['hvf', 'kvm', 'mshv', 'nvmm', 'qtest', 'tcg', 'whpx', 'xen'] } ## -# @AcceleratorInfo: Information about support for various accelerators +# @AcceleratorInfo: +# Information about support for various accelerators # # @enabled: the accelerator that is in use # @@ -85,7 +90,8 @@ { 'struct': 'AcceleratorInfo', 'data': {'enabled': 'Accelerator', 'present': ['Accelerator']} } ## -# @query-accelerators: Return information about accelerators +# @query-accelerators: +# Return information about accelerators # # Returns: @AcceleratorInfo # diff --git a/qapi/acpi-hest.json b/qapi/acpi-hest.json index 6a48e80082e..8db804df197 100644 --- a/qapi/acpi-hest.json +++ b/qapi/acpi-hest.json @@ -12,8 +12,9 @@ ## ## -# @inject-ghes-v2-error: Inject an error with additional ACPI 6.1 -# GHESv2 error information +# @inject-ghes-v2-error: +# Inject an error with additional ACPI 6.1 GHESv2 error +# information # # @cper: contains a base64 encoded string with raw data for a single # CPER record with Generic Error Status Block, Generic Error Data diff --git a/qapi/acpi.json b/qapi/acpi.json index ea6ad2cd45f..82e82d7cf89 100644 --- a/qapi/acpi.json +++ b/qapi/acpi.json @@ -12,8 +12,8 @@ ## ## -# @AcpiTableOptions: Specify an ACPI table on the -# command line to load. +# @AcpiTableOptions: +# Specify an ACPI table on the command line to load. # # At most one of @file and @data can be specified. The list of files # specified by any one of them is loaded and concatenated in order. @@ -79,7 +79,8 @@ { 'enum': 'ACPISlotType', 'data': [ 'DIMM', 'CPU' ] } ## -# @ACPIOSTInfo: OSPM Status Indication for a device. For description +# @ACPIOSTInfo: +# OSPM Status Indication for a device. For description # of possible values of @source and @status fields see "_OST (OSPM # Status Indication)" chapter of ACPI5.0 spec. # @@ -103,7 +104,8 @@ 'status': 'int' } } ## -# @query-acpi-ospm-status: Return a list of `ACPIOSTInfo` for devices +# @query-acpi-ospm-status: +# Return a list of `ACPIOSTInfo` for devices # that support status reporting via ACPI _OST method. # # Since: 2.1 @@ -120,7 +122,8 @@ { 'command': 'query-acpi-ospm-status', 'returns': ['ACPIOSTInfo'] } ## -# @ACPI_DEVICE_OST: Emitted when guest executes ACPI _OST method. +# @ACPI_DEVICE_OST: +# Emitted when guest executes ACPI _OST method. # # @info: OSPM Status Indication # diff --git a/qapi/audio.json b/qapi/audio.json index 62d64eabf1c..72190f20993 100644 --- a/qapi/audio.json +++ b/qapi/audio.json @@ -13,8 +13,9 @@ ## ## -# @AudiodevPerDirectionOptions: General audio backend options that are -# used for both playback and recording. +# @AudiodevPerDirectionOptions: +# General audio backend options that are used for both playback +# and recording. # # @mixing-engine: use QEMU's mixing engine to mix all streams inside # QEMU and convert audio formats when not supported by the @@ -50,7 +51,8 @@ '*buffer-length': 'uint32' } } ## -# @AudiodevGenericOptions: Generic driver-specific options. +# @AudiodevGenericOptions: +# Generic driver-specific options. # # @in: options of the capture stream # @@ -64,7 +66,8 @@ '*out': 'AudiodevPerDirectionOptions' } } ## -# @AudiodevDBusOptions: Options of the D-Bus audio backend. +# @AudiodevDBusOptions: +# Options of the D-Bus audio backend. # # @in: options of the capture stream # @@ -82,8 +85,9 @@ '*nsamples': 'uint32'} } ## -# @AudiodevAlsaPerDirectionOptions: Options of the ALSA backend that -# are used for both playback and recording. +# @AudiodevAlsaPerDirectionOptions: +# Options of the ALSA backend that are used for both playback and +# recording. # # @dev: the name of the ALSA device to use (default 'default') # @@ -102,7 +106,8 @@ '*try-poll': 'bool' } } ## -# @AudiodevAlsaOptions: Options of the ALSA audio backend. +# @AudiodevAlsaOptions: +# Options of the ALSA audio backend. # # @in: options of the capture stream # @@ -119,7 +124,8 @@ '*threshold': 'uint32' } } ## -# @AudiodevSndioOptions: Options of the sndio audio backend. +# @AudiodevSndioOptions: +# Options of the sndio audio backend. # # @in: options of the capture stream # @@ -139,8 +145,9 @@ '*latency': 'uint32'} } ## -# @AudiodevCoreaudioPerDirectionOptions: Options of the Core Audio -# backend that are used for both playback and recording. +# @AudiodevCoreaudioPerDirectionOptions: +# Options of the Core Audio backend that are used for both +# playback and recording. # # @buffer-count: number of buffers # @@ -152,7 +159,8 @@ '*buffer-count': 'uint32' } } ## -# @AudiodevCoreaudioOptions: Options of the coreaudio audio backend. +# @AudiodevCoreaudioOptions: +# Options of the coreaudio audio backend. # # @in: options of the capture stream # @@ -166,7 +174,8 @@ '*out': 'AudiodevCoreaudioPerDirectionOptions' } } ## -# @AudiodevDsoundOptions: Options of the DirectSound audio backend. +# @AudiodevDsoundOptions: +# Options of the DirectSound audio backend. # # @in: options of the capture stream # @@ -184,8 +193,9 @@ '*latency': 'uint32' } } ## -# @AudiodevJackPerDirectionOptions: Options of the JACK backend that -# are used for both playback and recording. +# @AudiodevJackPerDirectionOptions: +# Options of the JACK backend that are used for both playback and +# recording. # # @server-name: select from among several possible concurrent server # instances (default: environment variable $JACK_DEFAULT_SERVER if @@ -216,7 +226,8 @@ '*exact-name': 'bool' } } ## -# @AudiodevJackOptions: Options of the JACK audio backend. +# @AudiodevJackOptions: +# Options of the JACK audio backend. # # @in: options of the capture stream # @@ -230,8 +241,9 @@ '*out': 'AudiodevJackPerDirectionOptions' } } ## -# @AudiodevOssPerDirectionOptions: Options of the OSS backend that are -# used for both playback and recording. +# @AudiodevOssPerDirectionOptions: +# Options of the OSS backend that are used for both playback and +# recording. # # @dev: file name of the OSS device (default '/dev/dsp') # @@ -250,7 +262,8 @@ '*try-poll': 'bool' } } ## -# @AudiodevOssOptions: Options of the OSS audio backend. +# @AudiodevOssOptions: +# Options of the OSS audio backend. # # @in: options of the capture stream # @@ -278,8 +291,9 @@ '*dsp-policy': 'uint32' } } ## -# @AudiodevPaPerDirectionOptions: Options of the Pulseaudio backend -# that are used for both playback and recording. +# @AudiodevPaPerDirectionOptions: +# Options of the Pulseaudio backend that are used for both +# playback and recording. # # @name: name of the sink/source to use # @@ -301,7 +315,8 @@ '*latency': 'uint32' } } ## -# @AudiodevPaOptions: Options of the PulseAudio audio backend. +# @AudiodevPaOptions: +# Options of the PulseAudio audio backend. # # @in: options of the capture stream # @@ -318,8 +333,9 @@ '*server': 'str' } } ## -# @AudiodevPipewirePerDirectionOptions: Options of the PipeWire -# backend that are used for both playback and recording. +# @AudiodevPipewirePerDirectionOptions: +# Options of the PipeWire backend that are used for both playback +# and recording. # # @name: name of the sink/source to use # @@ -341,7 +357,8 @@ '*latency': 'uint32' } } ## -# @AudiodevPipewireOptions: Options of the PipeWire audio backend. +# @AudiodevPipewireOptions: +# Options of the PipeWire audio backend. # # @in: options of the capture stream # @@ -355,8 +372,9 @@ '*out': 'AudiodevPipewirePerDirectionOptions' } } ## -# @AudiodevSdlPerDirectionOptions: Options of the SDL audio backend -# that are used for both playback and recording. +# @AudiodevSdlPerDirectionOptions: +# Options of the SDL audio backend that are used for both playback +# and recording. # # @buffer-count: number of buffers (default 4) # @@ -368,7 +386,8 @@ '*buffer-count': 'uint32' } } ## -# @AudiodevSdlOptions: Options of the SDL audio backend. +# @AudiodevSdlOptions: +# Options of the SDL audio backend. # # @in: options of the recording stream # @@ -382,7 +401,8 @@ '*out': 'AudiodevSdlPerDirectionOptions' } } ## -# @AudiodevWavOptions: Options of the wav audio backend. +# @AudiodevWavOptions: +# Options of the wav audio backend. # # @in: options of the capture stream # @@ -399,7 +419,8 @@ '*path': 'str' } } ## -# @AudioFormat: An enumeration of possible audio formats. +# @AudioFormat: +# An enumeration of possible audio formats. # # @u8: unsigned 8 bit integer # @@ -421,7 +442,8 @@ 'data': [ 'u8', 's8', 'u16', 's16', 'u32', 's32', 'f32' ] } ## -# @AudiodevDriver: An enumeration of possible audio backend drivers. +# @AudiodevDriver: +# An enumeration of possible audio backend drivers. # # @jack: JACK audio backend (since 5.1) # @@ -443,7 +465,8 @@ 'wav' ] } ## -# @Audiodev: Options of an audio backend. +# @Audiodev: +# Options of an audio backend. # # @id: identifier of the backend # @@ -487,7 +510,8 @@ 'wav': 'AudiodevWavOptions' } } ## -# @query-audiodevs: Return information about audiodev configuration +# @query-audiodevs: +# Return information about audiodev configuration # # Since: 8.0 ## diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index c23fd26aaa7..8ff2a2c4c0b 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -530,23 +530,17 @@ def _get_doc_intro( line: str, info: QAPISourceInfo ) -> Tuple['QAPIDoc', Optional[str]]: - match = self._match_at_name_colon(line) - if not match: - raise QAPIParseError(self, "@name must end with ':'") + if not line.endswith(':'): + raise QAPIParseError(self, "line should end with ':'") # Invalid names are not checked here, but the name # provided *must* match the following definition, # which *is* validated in expr.py. - symbol = match.group(1) + symbol = line[1:-1] if not symbol: raise QAPIParseError(self, "name required after '@'") doc = QAPIDoc(info, symbol) - doc.ensure_untagged_section(info, QAPIDoc.Kind.INTRO) - text = line[match.end():] - if text: - doc.append_line(text) - return doc, self.get_doc_indented(doc) def get_doc(self) -> 'QAPIDoc': diff --git a/tests/qapi-schema/doc-missing-colon.err b/tests/qapi-schema/doc-missing-colon.err index bd5862b30f3..cbcea007153 100644 --- a/tests/qapi-schema/doc-missing-colon.err +++ b/tests/qapi-schema/doc-missing-colon.err @@ -1 +1 @@ -doc-missing-colon.json:4:1: @name must end with ':' +doc-missing-colon.json:4:1: line should end with ':' -- 2.54.0
