Repository: numpy/numpy
Pull request: DOC: update val to be scalar or array like optional closes #16901
Closes #16901 

Updates the docstring on `fill_diagonal` to change `val` param to be scalar or array like as optional. Modeled off docstring in [filled](https://github.com/numpy/numpy/blob/master/numpy/ma/core.py#L582)

<!-- Please be sure you are following the instructions in the dev guidelines
http://www.numpy.org/devdocs/dev/development_workflow.html
-->

<!-- We'd appreciate it if your commit message is properly formatted
http://www.numpy.org/devdocs/dev/development_workflow.html#writing-the-commit-message
-->


Problem statement:
DOC: Update fill_diagonal docstring
The current parameter description for `fill_diagonal` states that the fill value `val` must be a scalar. However, no input-checking is done on `val` and it turns out that array-likes with the same first dimension as `a` will also work, for example::

```python
>>> a = np.zeros((4, 5))
array([[0., 0., 0., 0., 0.],
       [0., 0., 0., 0., 0.],
       [0., 0., 0., 0., 0.],
       [0., 0., 0., 0., 0.]])
>>> np.fill_diagonal(a, np.arange(a.shape[0]))
>>> a
array([[0., 0., 0., 0., 0.],
       [0., 1., 0., 0., 0.],
       [0., 0., 2., 0., 0.],
       [0., 0., 0., 3., 0.]])
```

There are also already some examples in the docstring that use lists to fill the diagonal.

Hints from issue discussion:
Hey @rossbar I'll take this one on!

Commit message: DOC: update val to be scalar or array like optional closes #16901

Patch to review:
diff --git a/numpy/lib/index_tricks.py b/numpy/lib/index_tricks.py
index cba713edeb7c..9c04bb47fa0a 100644
--- a/numpy/lib/index_tricks.py
+++ b/numpy/lib/index_tricks.py
@@ -769,8 +769,8 @@ def fill_diagonal(a, val, wrap=False):
     a : array, at least 2-D.
       Array whose diagonal is to be filled, it gets modified in-place.
 
-    val : scalar
-      Value to be written on the diagonal, its type must be compatible with
+    val : scalar or array_like optional
+      Scalar value or array representing the value to be written on the diagonal, its type must be compatible with
       that of the array a.
 
     wrap : bool


Code review comments:
diff_hunk: @@ -769,8 +769,8 @@ def fill_diagonal(a, val, wrap=False):
     a : array, at least 2-D.
       Array whose diagonal is to be filled, it gets modified in-place.
 
-    val : scalar
-      Value to be written on the diagonal, its type must be compatible with
+    val : scalar or array_like optional
path: numpy/lib/index_tricks.py
text: @user1:
```suggestion
    val : scalar or array_like
```
`optional` is intended to signify when a keyword argument is optional, so it doesn't belong here.

diff_hunk: @@ -769,8 +769,8 @@ def fill_diagonal(a, val, wrap=False):
     a : array, at least 2-D.
       Array whose diagonal is to be filled, it gets modified in-place.
 
-    val : scalar
-      Value to be written on the diagonal, its type must be compatible with
+    val : scalar or array_like optional
+      Scalar value or array representing the value to be written on the diagonal, its type must be compatible with
path: numpy/lib/index_tricks.py
text: @user1:
Two comments here:
 1. The parameter description here should describe the behavior for both cases, i.e. when the value is a scalar, and when it is an array_like. The scalar case is obvious, but array_likes might be surprising: try `a = np.zeros((4, 5)); np.fill_diagonal(a, [1, 2])`, for example. There's no need to cover *every* single corner case here - the examples section is much better for illustrating details.
 2. Style nit - the lines should be kept at less than 80 characters per line.

@author:
@user1 I tried to address the the array parameter specifying that the length must be of the same length as the main diagonal. Not sure if the 80 characters per line is possible but definitely open to feedback on shortening it up!

Please take a look and do let me know :)