Improve boolean indexing docs
- [ X] closes #42384
- [ X] tests added / passed
- [ X] Ensure all linting tests pass, see [here](https://pandas.pydata.org/pandas-docs/dev/development/contributing.html#code-standards) for how to run them
- [ X] whatsnew entry
