Skip to content

Commit bbe197a

Browse files
authored
Update docstrings for elementwise functions (#2406)
The PR updates docstrings for elementwise functions to have a blank line prior `Default` value, also to add expected dtype of input arrays where missing, to align the dtypes with implementation and to fix some typos which were identified. Also a description of `include_initial` keyword is aligned for cumulative functions.
1 parent 4c66b58 commit bbe197a

6 files changed

+1269
-804
lines changed

.github/workflows/check-mkl-interfaces.yaml

+1-1
Original file line numberDiff line numberDiff line change
@@ -229,7 +229,7 @@ jobs:
229229
python -c "import dpnp; print(dpnp.__version__)"
230230
231231
- name: Run tests
232-
if: env.rerun-tests-on-failure == 'true'
232+
if: env.rerun-tests-on-failure != 'true'
233233
run: |
234234
python -m pytest -ra --pyargs dpnp.tests
235235
env:

dpnp/dpnp_iface_bitwise.py

+64-44
Original file line numberDiff line numberDiff line change
@@ -130,21 +130,17 @@ def binary_repr(num, width=None):
130130

131131
_BITWISE_AND_DOCSTRING = """
132132
Computes the bitwise AND of the underlying binary representation of each
133-
element `x1_i` of the input array `x1` with the respective element `x2_i`
134-
of the input array `x2`.
133+
element :math:`x1_i` of the input array `x1` with the respective element
134+
:math:`x2_i` of the input array `x2`.
135135
136136
For full documentation refer to :obj:`numpy.bitwise_and`.
137137
138138
Parameters
139139
----------
140140
x1 : {dpnp.ndarray, usm_ndarray, scalar}
141-
First input array, expected to have integer or boolean data type.
142-
Both inputs `x1` and `x2` can not be scalars at the same time.
141+
First input array, expected to have an integer or boolean data type.
143142
x2 : {dpnp.ndarray, usm_ndarray, scalar}
144-
Second input array, also expected to have integer or boolean data
145-
type. Both inputs `x1` and `x2` can not be scalars at the same time.
146-
If ``x1.shape != x2.shape``, they must be broadcastable to a common shape
147-
(which becomes the shape of the output).
143+
Second input array, also expected to have an integer or boolean data type.
148144
out : {None, dpnp.ndarray, usm_ndarray}, optional
149145
Output array to populate.
150146
Array must have the correct shape and the expected data type.
@@ -175,6 +171,13 @@ def binary_repr(num, width=None):
175171
:obj:`dpnp.binary_repr` : Return the binary representation of the input number
176172
as a string.
177173
174+
Notes
175+
-----
176+
At least one of `x1` or `x2` must be an array.
177+
178+
If ``x1.shape != x2.shape``, they must be broadcastable to a common shape
179+
(which becomes the shape of the output).
180+
178181
Examples
179182
--------
180183
>>> import dpnp as np
@@ -206,6 +209,7 @@ def binary_repr(num, width=None):
206209
'1100'
207210
>>> np.bitwise_and(np.array([14, 3]), 13)
208211
array([12, 1])
212+
209213
"""
210214

211215
bitwise_and = DPNPBinaryFunc(
@@ -225,7 +229,7 @@ def binary_repr(num, width=None):
225229
Parameters
226230
----------
227231
x : {dpnp.ndarray, usm_ndarray}
228-
Input array, expected to have integer or boolean data type.
232+
Input array, expected to have an integer data type.
229233
out : {None, dpnp.ndarray, usm_ndarray}, optional
230234
Output array to populate.
231235
Array must have the correct shape and the expected data type.
@@ -272,21 +276,17 @@ def binary_repr(num, width=None):
272276

273277
_BITWISE_OR_DOCSTRING = """
274278
Computes the bitwise OR of the underlying binary representation of each
275-
element `x1_i` of the input array `x1` with the respective element `x2_i`
276-
of the input array `x2`.
279+
element :math:`x1_i` of the input array `x1` with the respective element
280+
:math:`x2_i` of the input array `x2`.
277281
278282
For full documentation refer to :obj:`numpy.bitwise_or`.
279283
280284
Parameters
281285
----------
282286
x1 : {dpnp.ndarray, usm_ndarray, scalar}
283-
First input array, expected to have integer or boolean data type.
284-
Both inputs `x1` and `x2` can not be scalars at the same time.
287+
First input array, expected to have an integer or boolean data type.
285288
x2 : {dpnp.ndarray, usm_ndarray, scalar}
286-
Second input array, also expected to have integer or boolean data
287-
type. Both inputs `x1` and `x2` can not be scalars at the same time.
288-
If ``x1.shape != x2.shape``, they must be broadcastable to a common shape
289-
(which becomes the shape of the output).
289+
Second input array, also expected to have an integer or boolean data type.
290290
out : {None, dpnp.ndarray, usm_ndarray}, optional
291291
Output array to populate.
292292
Array must have the correct shape and the expected data type.
@@ -317,6 +317,13 @@ def binary_repr(num, width=None):
317317
:obj:`dpnp.binary_repr` : Return the binary representation of the input number
318318
as a string.
319319
320+
Notes
321+
-----
322+
At least one of `x1` or `x2` must be an array.
323+
324+
If ``x1.shape != x2.shape``, they must be broadcastable to a common shape
325+
(which becomes the shape of the output).
326+
320327
Examples
321328
--------
322329
>>> import dpnp as np
@@ -339,6 +346,7 @@ def binary_repr(num, width=None):
339346
array(29)
340347
>>> np.binary_repr(29)
341348
'11101'
349+
342350
"""
343351

344352
bitwise_or = DPNPBinaryFunc(
@@ -352,21 +360,17 @@ def binary_repr(num, width=None):
352360

353361
_BITWISE_XOR_DOCSTRING = """
354362
Computes the bitwise XOR of the underlying binary representation of each
355-
element `x1_i` of the input array `x1` with the respective element `x2_i`
356-
of the input array `x2`.
363+
element :math:`x1_i` of the input array `x1` with the respective element
364+
:math:`x2_i` of the input array `x2`.
357365
358366
For full documentation refer to :obj:`numpy.bitwise_xor`.
359367
360368
Parameters
361369
----------
362370
x1 : {dpnp.ndarray, usm_ndarray, scalar}
363-
First input array, expected to have integer or boolean data type.
364-
Both inputs `x1` and `x2` can not be scalars at the same time.
371+
First input array, expected to have an integer or boolean data type.
365372
x2 : {dpnp.ndarray, usm_ndarray, scalar}
366-
Second input array, also expected to have integer or boolean data
367-
type. Both inputs `x1` and `x2` can not be scalars at the same time.
368-
If ``x1.shape != x2.shape``, they must be broadcastable to a common shape
369-
(which becomes the shape of the output).
373+
Second input array, also expected to have an integer or boolean data type.
370374
out : {None, dpnp.ndarray, usm_ndarray}, optional
371375
Output array to populate.
372376
Array must have the correct shape and the expected data type.
@@ -397,6 +401,13 @@ def binary_repr(num, width=None):
397401
:obj:`dpnp.binary_repr` : Return the binary representation of the input number
398402
as a string.
399403
404+
Notes
405+
-----
406+
At least one of `x1` or `x2` must be an array.
407+
408+
If ``x1.shape != x2.shape``, they must be broadcastable to a common shape
409+
(which becomes the shape of the output).
410+
400411
Examples
401412
--------
402413
>>> import dpnp as np
@@ -423,6 +434,7 @@ def binary_repr(num, width=None):
423434
array(28)
424435
>>> np.binary_repr(28)
425436
'11100'
437+
426438
"""
427439

428440
bitwise_xor = DPNPBinaryFunc(
@@ -435,7 +447,7 @@ def binary_repr(num, width=None):
435447

436448

437449
_INVERT_DOCSTRING = """
438-
Inverts (flips) each bit for each element `x_i` of the input array `x`.
450+
Inverts (flips) each bit for each element :math:`x_i` of the input array `x`.
439451
440452
Note that :obj:`dpnp.bitwise_invert` is an alias of :obj:`dpnp.invert`.
441453
@@ -444,7 +456,7 @@ def binary_repr(num, width=None):
444456
Parameters
445457
----------
446458
x : {dpnp.ndarray, usm_ndarray}
447-
Input array, expected to have integer or boolean data type.
459+
Input array, expected to have an integer or boolean data type.
448460
out : {None, dpnp.ndarray, usm_ndarray}, optional
449461
Output array to populate.
450462
Array must have the correct shape and the expected data type.
@@ -514,9 +526,9 @@ def binary_repr(num, width=None):
514526
bitwise_invert = invert # bitwise_invert is an alias for invert
515527

516528
_LEFT_SHIFT_DOCSTRING = """
517-
Shifts the bits of each element `x1_i` of the input array x1 to the left by
518-
appending `x2_i` (i.e., the respective element in the input array `x2`) zeros to
519-
the right of `x1_i`.
529+
Shifts the bits of each element :math:`x1_i` of the input array `x1` to the
530+
left by appending :math:`x2_i` (i.e., the respective element in the input array
531+
`x2`) zeros to the right of :math:`x1_i`.
520532
521533
Note that :obj:`dpnp.bitwise_left_shift` is an alias of :obj:`dpnp.left_shift`.
522534
@@ -525,14 +537,10 @@ def binary_repr(num, width=None):
525537
Parameters
526538
----------
527539
x1 : {dpnp.ndarray, usm_ndarray, scalar}
528-
First input array, expected to have integer data type.
529-
Both inputs `x1` and `x2` can not be scalars at the same time.
540+
First input array, expected to have an integer data type.
530541
x2 : {dpnp.ndarray, usm_ndarray, scalar}
531-
Second input array, also expected to have integer data type.
542+
Second input array, also expected to have an integer data type.
532543
Each element must be greater than or equal to ``0``.
533-
Both inputs `x1` and `x2` can not be scalars at the same time.
534-
If ``x1.shape != x2.shape``, they must be broadcastable to a common shape
535-
(which becomes the shape of the output).
536544
out : {None, dpnp.ndarray, usm_ndarray}, optional
537545
Output array to populate.
538546
Array must have the correct shape and the expected data type.
@@ -560,6 +568,13 @@ def binary_repr(num, width=None):
560568
:obj:`dpnp.binary_repr` : Return the binary representation of the input number
561569
as a string.
562570
571+
Notes
572+
-----
573+
At least one of `x1` or `x2` must be an array.
574+
575+
If ``x1.shape != x2.shape``, they must be broadcastable to a common shape
576+
(which becomes the shape of the output).
577+
563578
Examples
564579
--------
565580
>>> import dpnp as np
@@ -580,6 +595,7 @@ def binary_repr(num, width=None):
580595
array(20)
581596
>>> np.binary_repr(20)
582597
'10100'
598+
583599
"""
584600

585601
left_shift = DPNPBinaryFunc(
@@ -594,8 +610,8 @@ def binary_repr(num, width=None):
594610

595611

596612
_RIGHT_SHIFT_DOCSTRING = """
597-
Shifts the bits of each element `x1_i` of the input array `x1` to the right
598-
according to the respective element `x2_i` of the input array `x2`.
613+
Shifts the bits of each element :math:`x1_i` of the input array `x1` to the
614+
right according to the respective element :math:`x2_i` of the input array `x2`.
599615
600616
Note that :obj:`dpnp.bitwise_right_shift` is an alias of :obj:`dpnp.right_shift`.
601617
@@ -604,14 +620,10 @@ def binary_repr(num, width=None):
604620
Parameters
605621
----------
606622
x1 : {dpnp.ndarray, usm_ndarray, scalar}
607-
First input array, expected to have integer data type.
608-
Both inputs `x1` and `x2` can not be scalars at the same time.
623+
First input array, expected to have an integer data type.
609624
x2 : {dpnp.ndarray, usm_ndarray, scalar}
610-
Second input array, also expected to have integer data type.
625+
Second input array, also expected to have an integer data type.
611626
Each element must be greater than or equal to ``0``.
612-
Both inputs `x1` and `x2` can not be scalars at the same time.
613-
If ``x1.shape != x2.shape``, they must be broadcastable to a common shape
614-
(which becomes the shape of the output).
615627
out : {None, dpnp.ndarray, usm_ndarray}, optional
616628
Output array to populate.
617629
Array must have the correct shape and the expected data type.
@@ -640,6 +652,13 @@ def binary_repr(num, width=None):
640652
:obj:`dpnp.binary_repr` : Return the binary representation of the input number
641653
as a string.
642654
655+
Notes
656+
-----
657+
At least one of `x1` or `x2` must be an array.
658+
659+
If ``x1.shape != x2.shape``, they must be broadcastable to a common shape
660+
(which becomes the shape of the output).
661+
643662
Examples
644663
--------
645664
>>> import dpnp as np
@@ -660,6 +679,7 @@ def binary_repr(num, width=None):
660679
array(5)
661680
>>> np.binary_repr(5)
662681
'101'
682+
663683
"""
664684

665685
right_shift = DPNPBinaryFunc(

dpnp/dpnp_iface_linearalgebra.py

+3-3
Original file line numberDiff line numberDiff line change
@@ -617,7 +617,7 @@ def inner(a, b):
617617
618618
See Also
619619
--------
620-
:obj:`dpnp.einsum` : Einstein summation convention..
620+
:obj:`dpnp.einsum` : Einstein summation convention.
621621
:obj:`dpnp.dot` : Generalized matrix product,
622622
using second last dimension of `b`.
623623
:obj:`dpnp.tensordot` : Sum products over arbitrary axes.
@@ -998,7 +998,7 @@ def matvec(
998998
999999
See Also
10001000
--------
1001-
:obj:`dpnp.vecdot` : Vector-vector product..
1001+
:obj:`dpnp.vecdot` : Vector-vector product.
10021002
:obj:`dpnp.vecmat` : Vector-matrix product.
10031003
:obj:`dpnp.matmul` : Matrix-matrix product.
10041004
:obj:`dpnp.einsum` : Einstein summation convention.
@@ -1502,7 +1502,7 @@ def vecmat(
15021502
15031503
See Also
15041504
--------
1505-
:obj:`dpnp.vecdot` : Vector-vector product..
1505+
:obj:`dpnp.vecdot` : Vector-vector product.
15061506
:obj:`dpnp.matvec` : Matrix-vector product.
15071507
:obj:`dpnp.matmul` : Matrix-matrix product.
15081508
:obj:`dpnp.einsum` : Einstein summation convention.

0 commit comments

Comments
 (0)