Document the objective (and differences with other formatters) more clearly

[hukkin]

Hey this seems like a cool tool!

I'm curious to know (and perhaps this is worth documenting?) what are the main differences to docformatter, seeing that this tool (IIUC) stems from the fact that docformatter was not optimal for pylint's use.

Does this tool do something that docformatter doesn't or vice versa? Is one more opinionated than the other?

Anyways, thanks for making this and publishing under a permissive license 👍

[DanielNoord]

One of the main "gripes" we had with docformatter was that PyCQA/docformatter#9 is still open. This is something we wanted to actively enforce in pylint and was actually the main reasons we were looking for a docstring formatter ourselves.
Another potential issue was that PyCQA/docformatter#75 was not resolved.

That's why I and @Pierre-Sassoulas opted to write our own tool. It's still in the early stages but for me the goal would be best described as:
"A docstring formatter that follows PEP8 and PEP257 but makes some of the more 'controversial' elements of the PEPs optional."

I think it would be good to document this objective more clearly when we get close to releasing 1.0 and the tool is an a more definitive shape. I'll keep this issue open to document that.

Feel free to ask any other question you might have btw 😄