Make docstrings to be nice with pydoc

In some doc-strings we use formatting rules specific to Sphinx, but which make the interactive help (pydoc) to look bad.

This issue is about:

• defining how we should write some recurrent stuff, like documenting input parameters and return values.
• rewrite the doc-strings so they look fine on pydoc, even if that means losing some features with Sphinx, like cross references.

Note. If we had the resources, we would do like Python does, and document things twice: once in the doc-strings and a feature rich version in the rst files. But in any case the doc-strings must be usable with pydoc, so lets start with that.

Không có tệp, bài kiểm thử hoặc điểm vào nào được nêu. Hãy bắt đầu bằng cách lập danh mục các docstring của dự án và so sánh đầu ra được kết xuất của chúng trong pydoc với các quy ước của Sphinx; được xem là hoàn tất khi đã thống nhất các quy tắc định dạng cho các tham số và giá trị trả về lặp lại, đồng thời các docstring đã được viết lại nhưng vẫn có thể sử dụng trong pydoc.