Docstrings are inconsistent (sanctioning convention)

[arekbulski]

I found several issues with the docstrings in the base FS class, but most dont seem to require much justification to change them. Once I am through with all the changes, I will put a Pull Request. I am pretty sure you will find all the clarifications justified (and corrections right).

There is a convention that I would like to be officially sanctioned, so we can keep the docstrings written in some unified, consistent way. Once sanctioned, I will apply it to my Pull Request.

• [ ] Make paragraphs in docstrings infinitely long. Currently most are broken apart at arbitrary position (hardly 80 chars) and few are not broken at all. Most editors support wrapping so there is no point.
• [ ] Method signatures and calls as one liners, infinitely long. Currently few methods have signatures broken one-argument-per-line which I find hard to look at. This is not a broadly used convention. And there are lines in the code that far longer than 80 chars already. I'd say we let the editors do the wraping.

@willmcgugan Please give a go?

[willmcgugan]

Docstrings, I see little point in changing. I don't always have wrapping on, because auto-wrapped code can be hard to read. Sphinx copes with the indentation as it is.

Method signatures, definitely not. It is fairly common, and blessed in pep8 to wrap long signatures like that.

I'm not apposed to tidying up of the code, but it has to be either pep8, or some justification other than personal preference behind it.

[arekbulski]

I withdraw the patch, it was too complex. I will resubmit with more strictly necessary changes to documentation.