Closed humitos closed 6 years ago
There is an example at https://www.python.org/dev/peps/pep-0257/#multi-line-docstrings, which seems to be correct and it gest reformatted:
$ docformatter documentation.py
--- before/documentation.py
+++ after/documentation.py
@@ -1,9 +1,8 @@
def method(self):
- """
- Form a complex number.
+ """Form a complex number.
- Keyword arguments:
- real -- the real part (default 0.0)
- imag -- the imaginary part (default 0.0)
+ Keyword arguments: real -- the real part (default 0.0) imag -- the
+ imaginary part (default 0.0)
+
"""
print('Docstring')
$ docformatter --version
docformatter 0.8
Thanks for the report. It uses a heuristic to determine whether or not to word wrap the description. I think we need to detect and avoid the cases you describe. I previously tried to do that for more extreme cases. But I think it makes sense to be even more cautious.
Can you try #18? Thanks
Thanks for being so responsive.
It works very good, but... (there is always one :) )
It seems that if it detects a list, it do not format the rest of the docstring at all. This is an example:
class Release(object):
"""Parse a release name.
* release-1.1/
* release-1.2/
* release-1.3/
* release-1.4/
* release-1.4.1/
* release-1.5/
- item 1
- item 2
- item 3
* my list contains different amount of words on each item
* short
* and not to short
Also, then I have a very simple paragraph with more information about the list that is described above this paragraph and it seems that if it already detected a list, then the following paragraph are not considered to be reformatted
"""
pass
class Release(object):
"""Parse a release name.
Also, then I have a very simple paragraph with more information about the list that is described above this paragraph
"""
pass
class Release(object):
"""Parse a release name.
Also, then I have a very simple paragraph with more information about the list that is described above this paragraph
What happen if I put a list after the first paragraph of the description?
* One item here...
* ... and here there is another one also
* This is the last one
"""
pass
$ ./docformatter/docformatter.py documentation3.py | colordiff
--- before/documentation3.py
+++ after/documentation3.py
@@ -18,13 +18,16 @@
Also, then I have a very simple paragraph with more information about the list that is described above this paragraph and it seems that if it already detected a list, then the following paragraph are not considered to be reformatted
+
"""
pass
class Release(object):
"""Parse a release name.
- Also, then I have a very simple paragraph with more information about the list that is described above this paragraph
+ Also, then I have a very simple paragraph with more information
+ about the list that is described above this paragraph
+
"""
pass
@@ -39,5 +42,6 @@
* One item here...
* ... and here there is another one also
* This is the last one
+
"""
pass
Anyway, it's a very good first start and I'm adding more examples to make it do not work on purpose but the gerenal case is solved by that PR.
Another thing, nothing to do with this issue. I just noticed that it didn't add the final dot to the paragraph that was reformatted. This one:
+ about the list that is described above this paragraph
Thanks for testing it! I'll merge the fix. Feel free to open additional issues for the above items. The first one would be an enhancement as docformatter
currently has no concept of splitting up the description into multiple chunks. But it seems like it would be good idea to format each chunk separately given your examples. For the second example, I hadn't considered adjusting punctuation of the description, but that might be a good enhancement as well.
Is it possible to allow one sentence on each line and avoid this re-formatting?