[DOC] Docstrings should contain minimal working examples

Brief Description of Fix

Having gone back-and-forth on this, I now think my original opinion in #329 should be made more nuanced.

Docstrings should contain minimal examples on how the function is used. They should also be tested using doctest, which I am happy to set up.

This improves the readability of the docs, and helps newcomer developers bring high-quality contributions by enforcing clarity on what is being accomplished. Notebooks still should be used, but as a series of more “elaborate” examples on data cleaning, with explanations.

@anzelpwj’s PR had a great starting point, and though it still doesn’t show both the functional and method-chaining use cases, I think it’s a great seed to build on top of.

This would involve a big effort, admittedly. I would not kickstart this until I have completed a single high-quality example (I might use flag_null as the starting point).

Start with the existing flag_null example and review the referenced PR as a model for the proposed docstring format. Determine how doctest should be set up, then add minimal working examples covering both functional and method-chaining use cases. Done means the examples are clear, tested with doctest, and notebooks remain focused on more elaborate data-cleaning examples.