[DOC] Add Usage Examples to Core Function Docstrings

[SimonBlanke]

Examples in docstrings provide various benefits for users and devs: You can see these examples during IDE hover tooltips, can generate examples for your auto generated documentation and can quickly see the usage pattern as a dev going through the code. Core public functions lack Examples sections in their docstrings.
Here are some of the public methods that would benefit from examples in docstrings:

• openml/datasets/functions.py:get_dataset()
• openml/datasets/functions.py:get_datasets()
• openml/tasks/functions.py:get_task()
• openml/runs/functions.py:run_model_on_task()
• openml/study/functions.py:get_suite()
• openml/study/functions.py:get_study()
• openml/study/functions.py:create_study()

[fkiraly]

I also noticed a few other issues with docstrings:

• missing defaults and types
• missing reference to retrieval from DB backend, e.g., what gets accessed
• missing reference to changes in database backend, e.g., what gets added, deleted

[Kashish564]

Hi @SimonBlanke and @fkiraly 👋
I’d like to work on this issue if it’s still available.

My plan is to:

• Add clear, minimal usage examples to the listed public functions’ docstrings
• While doing so, also improve missing types/defaults where obvious
• Clarify (briefly) what is retrieved from or written to the OpenML backend, where relevant

I’ll start with a small subset (e.g. get_dataset, get_task) and expand based on feedback.
Please let me know if this approach sounds good. Thanks!

[fkiraly]

feel free to go ahead, @Kashish564!
But make sure to pick something that is not currently being worked on - I think #1569 already deals with a number of these if not all.