Add DocGrammarBear for docstrings #1980

damngamerz · 2017-08-05T20:27:07Z

This bear checks for spellings and grammatical mistakes
on the descriptions of documentation comments.

For short term contributors: we understand that getting your commits well
defined like we require is a hard task and takes some learning. If you
look to help without wanting to contribute long term there's no need
for you to learn this. Just drop us a message and we'll take care of brushing
up your stuff for merge!

Checklist

I read the commit guidelines and I've followed
them.
I ran coala over my code locally. (All commits have to pass
individually. It is not sufficient to have "fixup commits" on your PR,
our bot will still report the issues for the previous commit.) You will
likely receive a lot of bot comments and build failures if coala does not
pass on every single commit!

After you submit your pull request, DO NOT click the 'Update Branch' button.
When asked for a rebase, consult coala.io/rebase
instead.

Please consider helping us by reviewing other peoples pull requests as well:

pick up any PR at https://coala.io/review
review it (check https://coala.io/reviewing for more info)
if you are sure that it needs work, use cobot mark wip <URL> to get it out
of the review queue.

The more you review, the more your score will grow at coala.io and we will
review your PRs faster!

gitmate-bot · 2017-08-05T20:28:05Z

tests/documentation/DocGrammarBearTest.py

+    test_bad1 = test('bad_file.py.test', 'bad_file.py.test.correct')
+    test_good1 = test('good_file.py.test', 'good_file.py.test')
+    test_good2 = test('good_file2.py.test', 'good_file2.py.test', {
+                      'languagetool_disable_rules': 'UPPERCASE_SENTENCE_START'})


Line is longer than allowed. (80 > 79)

LineLengthBear, severity NORMAL, section linelength.

gitmate-bot · 2017-08-05T20:28:06Z

tests/documentation/DocGrammarBearTest.py

+    test_bad1 = test('bad_file.py.test', 'bad_file.py.test.correct')
+    test_good1 = test('good_file.py.test', 'good_file.py.test')
+    test_good2 = test('good_file2.py.test', 'good_file2.py.test', {
+                      'languagetool_disable_rules': 'UPPERCASE_SENTENCE_START'})


E501 line too long (80 > 79 characters)'

PycodestyleBear (E501), severity NORMAL, section autopep8.

gitmate-bot · 2017-08-05T20:28:07Z

Comment on ae7a1d9.

No newline found between shortlog and body at HEAD commit. Please add one.

GitCommitBear, severity NORMAL, section commit.

NiklasMM

Please do not read test data from files, it's very hard to read the tests this way. Rather define the file content inside the test file. You can do that using string literals or even more conveniently, by building DocComment objects and assembling them

NiklasMM · 2017-08-06T10:52:10Z

bears/documentation/DocGrammarBear.py

+                              natural_language,
+                              languagetool_disable_rules):
+        """
+        This fixes the parsed documentation comment.


grammatically/spell correcting. need to add this 👍

also please mention the tool, and its links

NiklasMM · 2017-08-06T10:52:33Z

bears/documentation/DocGrammarBear.py

+
+        :param parsed:
+            Contains parsed documentation comment.
+        :param natural_language:


Why not call the parameter locale?

Because we need to specify language with locale en-US. These settings similar to the ones in LanguageToolBear.

Hm, yeah I see that it's take from there. But I'd still the parameter locale, that way users immediately know what input we expect.

cool then lets have locale 👍

NiklasMM · 2017-08-06T10:54:21Z

bears/documentation/DocGrammarBear.py

+            languagetool_disable_rules: typed_list(str)=()):
+        """
+        Checks the main description and comments description of documentation
+        with LanguageTool.


I'd like a little summary of what language tool can fix plus a link to the documentation.

SanketDG · 2017-08-06T13:03:23Z

bears/documentation/DocGrammarBear.py

+    AUTHORS_EMAILS = {'coala-devel@googlegroups.com'}
+    LICENSE = 'AGPL-3.0'
+    CAN_DETECT = {'Documentation', 'Spelling', 'Grammar'}
+    CAN_FIX = {'Documentation', 'Spelling', 'Grammar'}


can we have a cool asciinema?

SanketDG · 2017-08-06T13:04:40Z

bears/documentation/DocGrammarBear.py

+                              natural_language,
+                              languagetool_disable_rules):
+        """
+        This fixes the parsed documentation comment.


also please mention the tool, and its links

SanketDG · 2017-08-06T13:07:02Z

tests/documentation/DocGrammarBearTest.py

+    test_good1 = test('good_file.py.test', 'good_file.py.test')
+    test_good2 = test(
+        'good_file2.py.test', 'good_file2.py.test',
+        {'languagetool_disable_rules': 'UPPERCASE_SENTENCE_START'})


Add example: Fix spelling

SanketDG · 2017-08-06T13:08:06Z

tests/documentation/DocGrammarBearTest.py

+
+try:
+    import language_check
+    language_check


this line needed?

also can you use this decorator instead? http://github.com/coala/coala/blob/master/coalib/testing/BearTestHelper.py#L4

this line needed?

Yes as the same is followed in LanguageToolBear.

coala-bears/tests/natural_language/LanguageToolBearTest.py

Line 12 in 735dda7

language_check

gitmate-bot · 2017-08-09T12:26:24Z

tests/documentation/DocGrammarBearTest.py

@@ -0,0 +1,108 @@
+from queue import Queue
+import os.path


This file contains unused source code.

PyUnusedCodeBear, severity NORMAL, section flakes.

The issue can be fixed by applying the following patch:

--- a/tests/documentation/DocGrammarBearTest.py +++ b/tests/documentation/DocGrammarBearTest.py @@ -1,7 +1,5 @@ from queue import Queue -import os.path import unittest -import shutil from coalib.results.Diff import Diff from coalib.settings.Section import Section

gitmate-bot · 2017-08-09T15:07:05Z

bears/documentation/DocGrammarBear.py

+                LanguageTool
+                correct
+                return True
+            except ImportError: # pragma: no cover


E261 at least two spaces before inline comment'

PycodestyleBear (E261), severity NORMAL, section autopep8.

gitmate-bot · 2017-08-09T15:07:06Z

bears/documentation/DocGrammarBear.py

+                LanguageTool
+                correct
+                return True
+            except ImportError: # pragma: no cover


The code does not comply to PEP8.

PEP8Bear, severity NORMAL, section autopep8.

The issue can be fixed by applying the following patch:

--- a/bears/documentation/DocGrammarBear.py +++ b/bears/documentation/DocGrammarBear.py @@ -33,7 +33,7 @@ LanguageTool correct return True - except ImportError: # pragma: no cover + except ImportError: # pragma: no cover return 'Please install the `language-check` pip package.' def process_documentation(self,

yash-nisar · 2017-08-09T15:54:27Z

bears/documentation/DocGrammarBear.py

+    AUTHORS_EMAILS = {'coala-devel@googlegroups.com'}
+    LICENSE = 'AGPL-3.0'
+    ASCIINEMA_URL = 'https://asciinema.org/a/132564'
+    CAN_DETECT = {'Documentation', 'Spelling', 'Grammar'}


We don't need a CAN_DETECT if we're already mentioning a CAN_FIX 😉

is it? I see....

Yeah, because if we can fix something, we have already detected that thing. 😄

yash-nisar · 2017-08-09T15:55:32Z

tests/documentation/DocGrammarBearTest.py

+from coalib.testing.LocalBearTestHelper import execute_bear
+from coalib.testing.BearTestHelper import generate_skip_decorator
+from bears.documentation.DocGrammarBear import DocGrammarBear
+from string import Template


Maybe we should leave a line and then do the DocGrammarBear import.

yup looks good that way...
also Template import should be at top I feel.

We have an unofficial imports style (absent in most bears) in which we do the bear imports at the bottom. You can have a glance over the PEP8 import style. 😉

yeah move it to the top

SanketDG

looks good, small changes needed

SanketDG · 2017-08-09T21:51:34Z

tests/documentation/DocGrammarBearTest.py

+from coalib.testing.LocalBearTestHelper import execute_bear
+from coalib.testing.BearTestHelper import generate_skip_decorator
+from bears.documentation.DocGrammarBear import DocGrammarBear
+from string import Template


yeah move it to the top

SanketDG · 2017-08-09T21:51:57Z

tests/documentation/DocGrammarBearTest.py

+    import language_check
+    language_check
+except ImportError as err:
+    raise SkipTest(str(err))


I gave review comments on this on using a decorator

Oh you used it, then no need for this.

Yes, this is never importet and breaks my test suite :P

SanketDG · 2017-08-09T21:54:13Z

tests/documentation/DocGrammarBearTest.py

+                         '\n' +
+                         ':param xyz: $param_description' +
+                         ':return: $return_description' +
+                         '"""\n')


Now I am not so sure about using Template, .format() does this job easly

yeah let's just go with format https://pyformat.info/

Agree, also please use a multi line string with dedent. It's much easiert to read.

SanketDG · 2017-08-09T21:55:14Z

tests/documentation/DocGrammarBearTest.py

+    raise SkipTest(str(err))
+
+
+def make_docstring(main_desc: str='',


we need to explain this function, add some docs

NiklasMM

Looks good, the test suite looks much nicer now. I still recommend you use pytest's parametrize to get rid of more boilerplate code.

Things I'm missing in the testsuite:

Tests for a programming language that isn't Python
Tests for a natural language that isn't English

NiklasMM · 2017-08-10T05:45:03Z

bears/documentation/DocGrammarBear.py

+        and grammatic rules via LanguageTool.
+
+        :param parsed:
+            Contains parsed documentation comment.


Is this a DocComment object? If so, why not mention it?

no this is DocComment.parse() parsed documentation comment.

NiklasMM · 2017-08-10T05:49:00Z

tests/documentation/DocGrammarBearTest.py

+                         '\n' +
+                         ':param xyz: $param_description' +
+                         ':return: $return_description' +
+                         '"""\n')


Agree, also please use a multi line string with dedent. It's much easiert to read.

NiklasMM · 2017-08-10T05:51:01Z

tests/documentation/DocGrammarBearTest.py

+                       return_desc='Nothing.\n'),
+        {'languagetool_disable_rules': 'UPPERCASE_SENTENCE_START'})
+
+    test_explicit = test([


Please add a comment explainting what the test does.

NiklasMM · 2017-08-10T05:53:54Z

tests/documentation/DocGrammarBearTest.py

+                                ).splitlines(True)
+
+
+def test(test_file, expected_file, optional_setting=None):


This seems to be the core function of your test suite, why not give it a docstring?

we are giving a docstring/file data(explicit tests).
Maybe I should rename them to test_data, expected_data

NiklasMM · 2017-08-10T05:55:13Z

tests/documentation/DocGrammarBearTest.py

+        make_docstring(main_desc='This sentence doesn\'t have an '
+                                 'apostrophe\n'))
+
+    test_correct_grammar = test(


Instead of making the same docstring twice, make it once and pass it to the function twice. This make it immediately clear, that nothing changes.

NiklasMM · 2017-08-10T05:59:59Z

tests/documentation/DocGrammarBearTest.py

+    import language_check
+    language_check
+except ImportError as err:
+    raise SkipTest(str(err))


Yes, this is never importet and breaks my test suite :P

damngamerz · 2017-08-11T19:55:40Z

tests/documentation/DocGrammarBearTest.py

+        make_docstring(main_desc='Il monte s’il veut.\n'),
+        {'locale': 'fr',
+         'languagetool_disable_rules': 'FRENCH_WHITESPACE'})
+


This has been taken from
https://github.com/myint/language-check/blob/14bae49f6357c2bc592a11972c457665f7b30c28/test.py#L60

gitmate-bot · 2017-08-12T19:10:56Z

tests/documentation/DocGrammarBearTest.py

+    # which was breaking this test case.
+    test_language_french = unittest.skipIf(
+        platform.system() == 'Windows',
+        "language-check fails this test on windows")(


You do not use the preferred quotation marks.

QuotesBear, severity NORMAL, section python.

The issue can be fixed by applying the following patch:

--- a/tests/documentation/DocGrammarBearTest.py +++ b/tests/documentation/DocGrammarBearTest.py @@ -119,7 +119,7 @@ # which was breaking this test case. test_language_french = unittest.skipIf( platform.system() == 'Windows', - "language-check fails this test on windows")( + 'language-check fails this test on windows')( test( make_docstring(main_desc='il monte en haut si il veut.\n'), make_docstring(main_desc='Il monte s’il veut.\n'),

This bear checks for spellings and grammatical mistakes on the descriptions of documentation comments.

SanketDG · 2017-08-16T13:09:31Z

ack 112fa7d

SanketDG · 2017-08-16T13:12:02Z

@rultor merge

rultor · 2017-08-16T13:13:08Z

@rultor merge

@SanketDG OK, I'll try to merge now. You can check the progress of the merge here

rultor · 2017-08-16T13:15:00Z

@rultor merge

@SanketDG Done! FYI, the full log is here (took me 2min)

gitmate-bot added process/pending review size/XL labels Aug 5, 2017

gitmate-bot reviewed Aug 5, 2017

View reviewed changes

damngamerz force-pushed the docgrammarbear branch 2 times, most recently from b59185e to 05f9d01 Compare August 5, 2017 20:37

NiklasMM suggested changes Aug 6, 2017

View reviewed changes

SanketDG requested changes Aug 6, 2017

View reviewed changes

damngamerz force-pushed the docgrammarbear branch from 05f9d01 to a44c32d Compare August 9, 2017 12:25

gitmate-bot reviewed Aug 9, 2017

View reviewed changes

damngamerz force-pushed the docgrammarbear branch 2 times, most recently from a74c55b to f42423d Compare August 9, 2017 15:06

gitmate-bot reviewed Aug 9, 2017

View reviewed changes

damngamerz force-pushed the docgrammarbear branch 2 times, most recently from 861c8fb to 4983264 Compare August 9, 2017 15:12

yash-nisar reviewed Aug 9, 2017

View reviewed changes

SanketDG requested changes Aug 9, 2017

View reviewed changes

NiklasMM suggested changes Aug 10, 2017

View reviewed changes

damngamerz force-pushed the docgrammarbear branch from 4983264 to f78e22d Compare August 11, 2017 19:53

damngamerz commented Aug 11, 2017

View reviewed changes

damngamerz force-pushed the docgrammarbear branch 2 times, most recently from a4a1066 to 94f6f1b Compare August 12, 2017 19:09

gitmate-bot reviewed Aug 12, 2017

View reviewed changes

damngamerz force-pushed the docgrammarbear branch 2 times, most recently from 51c80c1 to 3918169 Compare August 12, 2017 19:27

NiklasMM approved these changes Aug 13, 2017

View reviewed changes

damngamerz force-pushed the docgrammarbear branch from 3918169 to b2f13c6 Compare August 14, 2017 23:32

damngamerz force-pushed the docgrammarbear branch 2 times, most recently from 369d4f8 to b86b53b Compare August 15, 2017 16:38

Add DocGrammarBear for docstrings

112fa7d

This bear checks for spellings and grammatical mistakes on the descriptions of documentation comments.

damngamerz force-pushed the docgrammarbear branch from b86b53b to 112fa7d Compare August 15, 2017 16:56

SanketDG approved these changes Aug 15, 2017

View reviewed changes

rultor merged commit 112fa7d into coala:master Aug 16, 2017

damngamerz deleted the docgrammarbear branch August 16, 2017 14:00

		raise SkipTest(str(err))


		def make_docstring(main_desc: str='',

		).splitlines(True)


		def test(test_file, expected_file, optional_setting=None):

Add DocGrammarBear for docstrings #1980

Add DocGrammarBear for docstrings #1980

Conversation

damngamerz commented Aug 5, 2017 • edited Loading

Checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gitmate-bot commented Aug 5, 2017

NiklasMM left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

SanketDG left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

NiklasMM left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

SanketDG commented Aug 16, 2017

SanketDG commented Aug 16, 2017

rultor commented Aug 16, 2017

rultor commented Aug 16, 2017

damngamerz commented Aug 5, 2017 •

edited

Loading