26ec4e53f2
The current doc generation doesn't care much about indentation levels,
but we would like to switch to an rST format, and rST does care about
indentation.
Make the doc comments more strongly consistent about indentation
for multiline constructs like:
@arg: description line 1
description line 2
Returns: line one
line 2
so that there is always exactly one space after the colon, and
subsequent lines align with the first.
This commit is a purely whitespace change, and it does not alter the
generated .texi files (because the texi generation code strips away
all the extra whitespace). This does mean that we end up with some
over-length lines.
Note that when the documentation for an argument fits on a single
line like this:
@arg: one line only
then stray extra spaces after the ':' don't affect the rST output, so
I have not attempted to methodically fix them, though the preference
is a single space here too.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-Id: <20200213175647.17628-10-peter.maydell@linaro.org>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Commit message tweaked]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
159 lines
3.5 KiB
Python
159 lines
3.5 KiB
Python
# -*- Mode: Python -*-
|
|
|
|
##
|
|
# = Socket data types
|
|
##
|
|
|
|
{ 'include': 'common.json' }
|
|
|
|
##
|
|
# @NetworkAddressFamily:
|
|
#
|
|
# The network address family
|
|
#
|
|
# @ipv4: IPV4 family
|
|
#
|
|
# @ipv6: IPV6 family
|
|
#
|
|
# @unix: unix socket
|
|
#
|
|
# @vsock: vsock family (since 2.8)
|
|
#
|
|
# @unknown: otherwise
|
|
#
|
|
# Since: 2.1
|
|
##
|
|
{ 'enum': 'NetworkAddressFamily',
|
|
'data': [ 'ipv4', 'ipv6', 'unix', 'vsock', 'unknown' ] }
|
|
|
|
##
|
|
# @InetSocketAddressBase:
|
|
#
|
|
# @host: host part of the address
|
|
# @port: port part of the address
|
|
##
|
|
{ 'struct': 'InetSocketAddressBase',
|
|
'data': {
|
|
'host': 'str',
|
|
'port': 'str' } }
|
|
|
|
##
|
|
# @InetSocketAddress:
|
|
#
|
|
# Captures a socket address or address range in the Internet namespace.
|
|
#
|
|
# @numeric: true if the host/port are guaranteed to be numeric,
|
|
# false if name resolution should be attempted. Defaults to false.
|
|
# (Since 2.9)
|
|
#
|
|
# @to: If present, this is range of possible addresses, with port
|
|
# between @port and @to.
|
|
#
|
|
# @ipv4: whether to accept IPv4 addresses, default try both IPv4 and IPv6
|
|
#
|
|
# @ipv6: whether to accept IPv6 addresses, default try both IPv4 and IPv6
|
|
#
|
|
# @keep-alive: enable keep-alive when connecting to this socket. Not supported
|
|
# for passive sockets. (Since 4.2)
|
|
#
|
|
# Since: 1.3
|
|
##
|
|
{ 'struct': 'InetSocketAddress',
|
|
'base': 'InetSocketAddressBase',
|
|
'data': {
|
|
'*numeric': 'bool',
|
|
'*to': 'uint16',
|
|
'*ipv4': 'bool',
|
|
'*ipv6': 'bool',
|
|
'*keep-alive': 'bool' } }
|
|
|
|
##
|
|
# @UnixSocketAddress:
|
|
#
|
|
# Captures a socket address in the local ("Unix socket") namespace.
|
|
#
|
|
# @path: filesystem path to use
|
|
#
|
|
# Since: 1.3
|
|
##
|
|
{ 'struct': 'UnixSocketAddress',
|
|
'data': {
|
|
'path': 'str' } }
|
|
|
|
##
|
|
# @VsockSocketAddress:
|
|
#
|
|
# Captures a socket address in the vsock namespace.
|
|
#
|
|
# @cid: unique host identifier
|
|
# @port: port
|
|
#
|
|
# Note: string types are used to allow for possible future hostname or
|
|
# service resolution support.
|
|
#
|
|
# Since: 2.8
|
|
##
|
|
{ 'struct': 'VsockSocketAddress',
|
|
'data': {
|
|
'cid': 'str',
|
|
'port': 'str' } }
|
|
|
|
##
|
|
# @SocketAddressLegacy:
|
|
#
|
|
# Captures the address of a socket, which could also be a named file descriptor
|
|
#
|
|
# Note: This type is deprecated in favor of SocketAddress. The
|
|
# difference between SocketAddressLegacy and SocketAddress is that the
|
|
# latter is a flat union rather than a simple union. Flat is nicer
|
|
# because it avoids nesting on the wire, i.e. that form has fewer {}.
|
|
|
|
#
|
|
# Since: 1.3
|
|
##
|
|
{ 'union': 'SocketAddressLegacy',
|
|
'data': {
|
|
'inet': 'InetSocketAddress',
|
|
'unix': 'UnixSocketAddress',
|
|
'vsock': 'VsockSocketAddress',
|
|
'fd': 'String' } }
|
|
|
|
##
|
|
# @SocketAddressType:
|
|
#
|
|
# Available SocketAddress types
|
|
#
|
|
# @inet: Internet address
|
|
#
|
|
# @unix: Unix domain socket
|
|
#
|
|
# @vsock: VMCI address
|
|
#
|
|
# @fd: decimal is for file descriptor number, otherwise a file descriptor name.
|
|
# Named file descriptors are permitted in monitor commands, in combination
|
|
# with the 'getfd' command. Decimal file descriptors are permitted at
|
|
# startup or other contexts where no monitor context is active.
|
|
#
|
|
# Since: 2.9
|
|
##
|
|
{ 'enum': 'SocketAddressType',
|
|
'data': [ 'inet', 'unix', 'vsock', 'fd' ] }
|
|
|
|
##
|
|
# @SocketAddress:
|
|
#
|
|
# Captures the address of a socket, which could also be a named file
|
|
# descriptor
|
|
#
|
|
# @type: Transport type
|
|
#
|
|
# Since: 2.9
|
|
##
|
|
{ 'union': 'SocketAddress',
|
|
'base': { 'type': 'SocketAddressType' },
|
|
'discriminator': 'type',
|
|
'data': { 'inet': 'InetSocketAddress',
|
|
'unix': 'UnixSocketAddress',
|
|
'vsock': 'VsockSocketAddress',
|
|
'fd': 'String' } }
|