17336, "cassella", "Should chpldoc emit spaces around binary operators?", "2021-03-04T04:47:55Z"
Should chpldoc emit spaces around binary operators? This came up in
#17169, but was deferred to this new issue for discussion.
The three types of approaches are the current behavior (never emit
spaces), the simple alternative (always emit spaces), and various
flavors of sometimes emit spaces.
The test added in that issue has a variety of expressions. The
no-spaces output:
.. data:: var pp = a+b+c
.. data:: var Pp = a+b+c
.. data:: var pP = a+b+c
.. data:: var pppp = a+b+c+d+e
.. data:: var PpPp = a+b+c+d+e
.. data:: var mm = a-b-c
.. data:: var Mm = a-b-c
.. data:: var mM = a-(b-c)
.. data:: var pm = a+b-c
.. data:: var Pm = a+b-c
.. data:: var pM = a+b-c
.. data:: var mp = a-b+c
.. data:: var Mp = a-b+c
.. data:: var mP = a-(b+c)
.. data:: var unarypunaryp = ++a
.. data:: var unarymunarym = --a
.. data:: var unarypunarym = +-a
.. data:: var unarymunaryp = -+a
.. data:: var unarypP = +(a+b)
.. data:: var unarypM = +(a-b)
.. data:: var unarymP = -(a+b)
.. data:: var unarymM = -(a-b)
.. data:: var unarynp = ~(a+b)
.. data:: var binpunarym = a+-b
.. data:: var andub = a&&!b
.. data:: var andubor = a&&!(b||c)
.. data:: var unarympow = -a**b
.. data:: var Unarympow = (-a)**b
.. data:: var powunarym = a**-b
.. data:: var powunarymP = a**-(b+c)
.. data:: var unarymcast = -a: uint
.. data:: var Unarymcast = (-a): uint
.. data:: var tp = a*b+c
.. data:: var Tp = a*b+c
.. data:: var tP = a*(b+c)
.. data:: var pt = a+b*c
.. data:: var Pt = (a+b)*c
.. data:: var pT = a+b*c
.. data:: var td = a*b/c
.. data:: var Td = a*b/c
.. data:: var tD = a*b/c
.. data:: var dt = a/b*c
.. data:: var Dt = a/b*c
.. data:: var dT = a/(b*c)
.. data:: var ll = a<<b<<c
.. data:: var Ll = a<<b<<c
.. data:: var lL = a<<(b<<c)
.. data:: var ee = a==b==c
.. data:: var Ee = a==b==c
.. data:: var eE = a==(b==c)
.. data:: var xx = a**b**c
.. data:: var xX = a**b**c
.. data:: var Xx = (a**b)**c
.. data:: var xpx = a**b+c**d
.. data:: var xPx = a**(b+c)**d
.. data:: var xPX = a**(b+c**d)
.. data:: var ooo = a||b||c||d
.. data:: var oao = a||b&&c||d
.. data:: var Oao = (a||b)&&c||d
.. data:: var OAo = (a||b)&&c||d
.. data:: var OaO = (a||b)&&(c||d)
.. data:: var oaO = a||b&&(c||d)
.. data:: var oAO = a||b&&(c||d)
.. data:: var oAo = a||b&&c||d
.. data:: var unarybo = !a||b
.. data:: var unarybO = !(a||b)
.. data:: var booo = a|b|c|d
.. data:: var boao = a|b&c|d
.. data:: var bOao = (a|b)&c|d
.. data:: var bOAo = (a|b)&c|d
.. data:: var bOaO = (a|b)&(c|d)
.. data:: var boaO = a|b&(c|d)
.. data:: var boAO = a|b&(c|d)
.. data:: var boAo = a|b&c|d
.. data:: var boxo = a|b^c|d
.. data:: var bOxo = (a|b)^c|d
.. data:: var bOxO = (a|b)^(c|d)
.. data:: var boXo = a|b^c|d
.. data:: var bxxx = a^b^c^d
.. data:: var bxax = a^b&c^d
.. data:: var bXax = (a^b)&c^d
.. data:: var bXaX = (a^b)&(c^d)
.. data:: var bxAx = a^b&c^d
.. data:: var addfoo = a+foo(b)
.. data:: var fooadd = foo(a)+b
.. data:: var fooAdd = foo(a+b)
Spaces everywhere:
.. data:: var pp = a + b + c
.. data:: var Pp = a + b + c
.. data:: var pP = a + b + c
.. data:: var pppp = a + b + c + d + e
.. data:: var PpPp = a + b + c + d + e
.. data:: var mm = a - b - c
.. data:: var Mm = a - b - c
.. data:: var mM = a - (b - c)
.. data:: var pm = a + b - c
.. data:: var Pm = a + b - c
.. data:: var pM = a + b - c
.. data:: var mp = a - b + c
.. data:: var Mp = a - b + c
.. data:: var mP = a - (b + c)
.. data:: var unarypunaryp = ++a
.. data:: var unarymunarym = --a
.. data:: var unarypunarym = +-a
.. data:: var unarymunaryp = -+a
.. data:: var unarypP = +(a + b)
.. data:: var unarypM = +(a - b)
.. data:: var unarymP = -(a + b)
.. data:: var unarymM = -(a - b)
.. data:: var unarynp = ~(a + b)
.. data:: var binpunarym = a + -b
.. data:: var andub = a && !b
.. data:: var andubor = a && !(b || c)
.. data:: var unarympow = -a ** b
.. data:: var Unarympow = (-a) ** b
.. data:: var powunarym = a ** -b
.. data:: var powunarymP = a ** -(b + c)
.. data:: var unarymcast = -a: uint
.. data:: var Unarymcast = (-a): uint
.. data:: var tp = a * b + c
.. data:: var Tp = a * b + c
.. data:: var tP = a * (b + c)
.. data:: var pt = a + b * c
.. data:: var Pt = (a + b) * c
.. data:: var pT = a + b * c
.. data:: var td = a * b / c
.. data:: var Td = a * b / c
.. data:: var tD = a * b / c
.. data:: var dt = a / b * c
.. data:: var Dt = a / b * c
.. data:: var dT = a / (b * c)
.. data:: var ll = a << b << c
.. data:: var Ll = a << b << c
.. data:: var lL = a << (b << c)
.. data:: var ee = a == b == c
.. data:: var Ee = a == b == c
.. data:: var eE = a == (b == c)
.. data:: var xx = a ** b ** c
.. data:: var xX = a ** b ** c
.. data:: var Xx = (a ** b) ** c
.. data:: var xpx = a ** b + c ** d
.. data:: var xPx = a ** (b + c) ** d
.. data:: var xPX = a ** (b + c ** d)
.. data:: var ooo = a || b || c || d
.. data:: var oao = a || b && c || d
.. data:: var Oao = (a || b) && c || d
.. data:: var OAo = (a || b) && c || d
.. data:: var OaO = (a || b) && (c || d)
.. data:: var oaO = a || b && (c || d)
.. data:: var oAO = a || b && (c || d)
.. data:: var oAo = a || b && c || d
.. data:: var unarybo = !a || b
.. data:: var unarybO = !(a || b)
.. data:: var booo = a | b | c | d
.. data:: var boao = a | b & c | d
.. data:: var bOao = (a | b) & c | d
.. data:: var bOAo = (a | b) & c | d
.. data:: var bOaO = (a | b) & (c | d)
.. data:: var boaO = a | b & (c | d)
.. data:: var boAO = a | b & (c | d)
.. data:: var boAo = a | b & c | d
.. data:: var boxo = a | b ^ c | d
.. data:: var bOxo = (a | b) ^ c | d
.. data:: var bOxO = (a | b) ^ (c | d)
.. data:: var boXo = a | b ^ c | d
.. data:: var bxxx = a ^ b ^ c ^ d
.. data:: var bxax = a ^ b & c ^ d
.. data:: var bXax = (a ^ b) & c ^ d
.. data:: var bXaX = (a ^ b) & (c ^ d)
.. data:: var bxAx = a ^ b & c ^ d
.. data:: var addfoo = a + foo(b)
.. data:: var fooadd = foo(a) + b
.. data:: var fooAdd = foo(a + b)
There are a few parts of documentation produced by make docs that
differ in these approaches:
diff -r doc-master/html/_sources/builtins/Bytes.rst.txt doc/html/_sources/builtins/Bytes.rst.txt
185c185
< .. function:: proc createBytesWithNewBuffer(x: c_ptr(?t), length: int, size = length+1)
> .. function:: proc createBytesWithNewBuffer(x: c_ptr(?t), length: int, size = length + 1)
diff -r doc-master/html/_sources/builtins/String.rst.txt doc/html/_sources/builtins/String.rst.txt
305c305
< .. function:: proc createStringWithNewBuffer(x: c_ptr(?t), length: int, size = length+1, policy = decodePolicy.strict) throws
> .. function:: proc createStringWithNewBuffer(x: c_ptr(?t), length: int, size = length + 1, policy = decodePolicy.strict) throws
diff -r doc-master/html/_sources/modules/packages/DistributedBag.rst.txt doc/html/_sources/modules/packages/DistributedBag.rst.txt
116c116
< .. data:: config const distributedBagMaxBlockSize = 1024*1024
> .. data:: config const distributedBagMaxBlockSize = 1024 * 1024
diff -r doc-master/html/_sources/modules/packages/HDF5/C_HDF5.rst.txt doc/html/_sources/modules/packages/HDF5/C_HDF5.rst.txt
3246c3246
< .. data:: param H5F_OBJ_ALL = H5F_OBJ_FILE|H5F_OBJ_DATASET|H5F_OBJ_GROUP|H5F_OBJ_DATATYPE|H5F_OBJ_ATTR
> .. data:: param H5F_OBJ_ALL = H5F_OBJ_FILE | H5F_OBJ_DATASET | H5F_OBJ_GROUP | H5F_OBJ_DATATYPE | H5F_OBJ_ATTR
diff -r doc-master/html/_sources/modules/standard/GMP.rst.txt doc/html/_sources/modules/standard/GMP.rst.txt
132c132
< .. type:: type mpz_t = 1*__mpz_struct
> .. type:: type mpz_t = 1 * __mpz_struct
136c136
< .. type:: type mpf_t = 1*__mpf_struct
> .. type:: type mpf_t = 1 * __mpf_struct
140c140
< .. type:: type gmp_randstate_t = 1*__gmp_randstate_struct
> .. type:: type gmp_randstate_t = 1 * __gmp_randstate_struct
diff -r doc-master/html/_sources/modules/standard/IO.rst.txt doc/html/_sources/modules/standard/IO.rst.txt
1686c1686
< .. method:: proc channel.readline(arg: [] uint(8), out numRead: int, start = arg.domain.low, amount = arg.domain.high-start+1): bool throws
> .. method:: proc channel.readline(arg: [] uint(8), out numRead: int, start = arg.domain.low, amount = arg.domain.high - start + 1): bool throws
diff -r doc-master/html/_sources/modules/standard/Math.rst.txt doc/html/_sources/modules/standard/Math.rst.txt
125c125
< .. function:: proc abs(z: complex(?w)): real(w/2)
> .. function:: proc abs(z: complex(?w)): real(w / 2)
132c132
< .. function:: proc carg(z: complex(?w)): real(w/2)
> .. function:: proc carg(z: complex(?w)): real(w / 2)
311c311
< .. function:: proc cproj(z: complex(?w)): real(w/2)
> .. function:: proc cproj(z: complex(?w)): real(w / 2)
diff -r doc-master/html/_sources/modules/standard/Random.rst.txt doc/html/_sources/modules/standard/Random.rst.txt
82c82
< .. type:: type RandomStream = if defaultRNG==RNG.PCG then PCGRandomStream else NPBRandomStream
> .. type:: type RandomStream = if defaultRNG == RNG.PCG then PCGRandomStream else NPBRandomStream
diff -r doc-master/rst/builtins/Bytes.rst doc/rst/builtins/Bytes.rst
185c185
< .. function:: proc createBytesWithNewBuffer(x: c_ptr(?t), length: int, size = length+1)
> .. function:: proc createBytesWithNewBuffer(x: c_ptr(?t), length: int, size = length + 1)
diff -r doc-master/rst/builtins/String.rst doc/rst/builtins/String.rst
305c305
< .. function:: proc createStringWithNewBuffer(x: c_ptr(?t), length: int, size = length+1, policy = decodePolicy.strict) throws
> .. function:: proc createStringWithNewBuffer(x: c_ptr(?t), length: int, size = length + 1, policy = decodePolicy.strict) throws
diff -r doc-master/rst/modules/packages/DistributedBag.rst doc/rst/modules/packages/DistributedBag.rst
116c116
< .. data:: config const distributedBagMaxBlockSize = 1024*1024
> .. data:: config const distributedBagMaxBlockSize = 1024 * 1024
diff -r doc-master/rst/modules/packages/HDF5/C_HDF5.rst doc/rst/modules/packages/HDF5/C_HDF5.rst
3246c3246
< .. data:: param H5F_OBJ_ALL = H5F_OBJ_FILE|H5F_OBJ_DATASET|H5F_OBJ_GROUP|H5F_OBJ_DATATYPE|H5F_OBJ_ATTR
> .. data:: param H5F_OBJ_ALL = H5F_OBJ_FILE | H5F_OBJ_DATASET | H5F_OBJ_GROUP | H5F_OBJ_DATATYPE | H5F_OBJ_ATTR
diff -r doc-master/rst/modules/standard/GMP.rst doc/rst/modules/standard/GMP.rst
132c132
< .. type:: type mpz_t = 1*__mpz_struct
> .. type:: type mpz_t = 1 * __mpz_struct
136c136
< .. type:: type mpf_t = 1*__mpf_struct
> .. type:: type mpf_t = 1 * __mpf_struct
140c140
< .. type:: type gmp_randstate_t = 1*__gmp_randstate_struct
> .. type:: type gmp_randstate_t = 1 * __gmp_randstate_struct
diff -r doc-master/rst/modules/standard/IO.rst doc/rst/modules/standard/IO.rst
1686c1686
< .. method:: proc channel.readline(arg: [] uint(8), out numRead: int, start = arg.domain.low, amount = arg.domain.high-start+1): bool throws
> .. method:: proc channel.readline(arg: [] uint(8), out numRead: int, start = arg.domain.low, amount = arg.domain.high - start + 1): bool throws
diff -r doc-master/rst/modules/standard/Math.rst doc/rst/modules/standard/Math.rst
125c125
< .. function:: proc abs(z: complex(?w)): real(w/2)
> .. function:: proc abs(z: complex(?w)): real(w / 2)
132c132
< .. function:: proc carg(z: complex(?w)): real(w/2)
> .. function:: proc carg(z: complex(?w)): real(w / 2)
311c311
< .. function:: proc cproj(z: complex(?w)): real(w/2)
> .. function:: proc cproj(z: complex(?w)): real(w / 2)
diff -r doc-master/rst/modules/standard/Random.rst doc/rst/modules/standard/Random.rst
82c82
< .. type:: type RandomStream = if defaultRNG==RNG.PCG then PCGRandomStream else NPBRandomStream
> .. type:: type RandomStream = if defaultRNG == RNG.PCG then PCGRandomStream else NPBRandomStream
The third family of approaches would involve identifying picking one
or the other approach as a default, and identifying cases that should
behave the other way.