improve docstrings based on @ElDeveloper's comments