Add info in docblock about warnings

- Added a paragraph indicating inability to filter non-scalar values,
  and that a warning will be raised in such circumstances.
- Updated return annotations to indicate a "mixed" possibility.