outdated docstrings

While helping a colleague to find a relevant class/method for a task, I realized that there are many docstrings in the current codebase that are either incomplete or outdated after many changes over time. This issue to track the need for updating and improving the docstrings. 
