Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add DocGrammarBear for docstrings #1980

Merged
merged 1 commit into from Aug 16, 2017
Merged

Conversation

@damngamerz
Copy link
Member

@damngamerz damngamerz commented Aug 5, 2017

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:

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

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'})

This comment has been minimized.

@gitmate-bot

gitmate-bot Aug 5, 2017
Collaborator

Line is longer than allowed. (80 > 79)

LineLengthBear, severity NORMAL, section linelength.

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'})

This comment has been minimized.

@gitmate-bot

gitmate-bot Aug 5, 2017
Collaborator

E501 line too long (80 > 79 characters)'

PycodestyleBear (E501), severity NORMAL, section autopep8.

@gitmate-bot
Copy link
Collaborator

@gitmate-bot gitmate-bot commented Aug 5, 2017

Comment on ae7a1d9.

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

GitCommitBear, severity NORMAL, section commit.

@damngamerz damngamerz force-pushed the damngamerz:docgrammarbear branch 2 times, most recently from b59185e to 05f9d01 Aug 5, 2017
Copy link
Contributor

@NiklasMM NiklasMM left a comment

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

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

This comment has been minimized.

@NiklasMM

NiklasMM Aug 6, 2017
Contributor

How?

This comment has been minimized.

@damngamerz

damngamerz Aug 6, 2017
Author Member

grammatically/spell correcting. need to add this 👍

This comment has been minimized.

@SanketDG

SanketDG Aug 6, 2017
Member

also please mention the tool, and its links

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

This comment has been minimized.

@NiklasMM

NiklasMM Aug 6, 2017
Contributor

Why not call the parameter locale?

This comment has been minimized.

@damngamerz

damngamerz Aug 6, 2017
Author Member

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

This comment has been minimized.

@NiklasMM

NiklasMM Aug 6, 2017
Contributor

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.

This comment has been minimized.

@damngamerz

damngamerz Aug 6, 2017
Author Member

cool then lets have locale 👍

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

This comment has been minimized.

@NiklasMM

NiklasMM Aug 6, 2017
Contributor

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

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

This comment has been minimized.

@SanketDG

SanketDG Aug 6, 2017
Member

can we have a cool asciinema?

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

This comment has been minimized.

@SanketDG

SanketDG Aug 6, 2017
Member

also please mention the tool, and its links

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'})

This comment has been minimized.

@SanketDG

SanketDG Aug 6, 2017
Member

Add example: Fix spelling


try:
import language_check
language_check

This comment has been minimized.

@SanketDG

SanketDG Aug 6, 2017
Member

this line needed?

This comment has been minimized.

This comment has been minimized.

@damngamerz

damngamerz Aug 9, 2017
Author Member

this line needed?

Yes as the same is followed in LanguageToolBear.

@damngamerz damngamerz force-pushed the damngamerz:docgrammarbear branch from 05f9d01 to a44c32d Aug 9, 2017
@@ -0,0 +1,108 @@
from queue import Queue
import os.path

This comment has been minimized.

@gitmate-bot

gitmate-bot Aug 9, 2017
Collaborator

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
@damngamerz damngamerz force-pushed the damngamerz:docgrammarbear branch 2 times, most recently from a74c55b to f42423d Aug 9, 2017
LanguageTool
correct
return True
except ImportError: # pragma: no cover

This comment has been minimized.

@gitmate-bot

gitmate-bot Aug 9, 2017
Collaborator

E261 at least two spaces before inline comment'

PycodestyleBear (E261), severity NORMAL, section autopep8.

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

This comment has been minimized.

@gitmate-bot

gitmate-bot Aug 9, 2017
Collaborator

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,
@damngamerz damngamerz force-pushed the damngamerz:docgrammarbear branch 2 times, most recently from 861c8fb to 4983264 Aug 9, 2017
AUTHORS_EMAILS = {'coala-devel@googlegroups.com'}
LICENSE = 'AGPL-3.0'
ASCIINEMA_URL = 'https://asciinema.org/a/132564'
CAN_DETECT = {'Documentation', 'Spelling', 'Grammar'}

This comment has been minimized.

@yash-nisar

yash-nisar Aug 9, 2017
Member

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

This comment has been minimized.

@damngamerz

damngamerz Aug 9, 2017
Author Member

is it? I see....

This comment has been minimized.

@yash-nisar

yash-nisar Aug 9, 2017
Member

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

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

This comment has been minimized.

@yash-nisar

yash-nisar Aug 9, 2017
Member

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

This comment has been minimized.

@damngamerz

damngamerz Aug 9, 2017
Author Member

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

This comment has been minimized.

@yash-nisar

yash-nisar Aug 9, 2017
Member

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. 😉

This comment has been minimized.

@SanketDG

SanketDG Aug 9, 2017
Member

yeah move it to the top

Copy link
Member

@SanketDG SanketDG left a comment

looks good, small changes needed

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

This comment has been minimized.

@SanketDG

SanketDG Aug 9, 2017
Member

yeah move it to the top

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

This comment has been minimized.

@SanketDG

SanketDG Aug 9, 2017
Member

I gave review comments on this on using a decorator

This comment has been minimized.

@SanketDG

SanketDG Aug 9, 2017
Member

Oh you used it, then no need for this.

This comment has been minimized.

@NiklasMM

NiklasMM Aug 10, 2017
Contributor

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

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

This comment has been minimized.

@SanketDG

SanketDG Aug 9, 2017
Member

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

This comment has been minimized.

@SanketDG

SanketDG Aug 9, 2017
Member

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

This comment has been minimized.

@NiklasMM

NiklasMM Aug 10, 2017
Contributor

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

raise SkipTest(str(err))


def make_docstring(main_desc: str='',

This comment has been minimized.

@SanketDG

SanketDG Aug 9, 2017
Member

we need to explain this function, add some docs

Copy link
Contributor

@NiklasMM NiklasMM left a comment

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
and grammatic rules via LanguageTool.
:param parsed:
Contains parsed documentation comment.

This comment has been minimized.

@NiklasMM

NiklasMM Aug 10, 2017
Contributor

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

This comment has been minimized.

@damngamerz

damngamerz Aug 11, 2017
Author Member

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

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

This comment has been minimized.

@NiklasMM

NiklasMM Aug 10, 2017
Contributor

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

return_desc='Nothing.\n'),
{'languagetool_disable_rules': 'UPPERCASE_SENTENCE_START'})

test_explicit = test([

This comment has been minimized.

@NiklasMM

NiklasMM Aug 10, 2017
Contributor

Please add a comment explainting what the test does.

).splitlines(True)


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

This comment has been minimized.

@NiklasMM

NiklasMM Aug 10, 2017
Contributor

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

This comment has been minimized.

@damngamerz

damngamerz Aug 11, 2017
Author Member

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

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

test_correct_grammar = test(

This comment has been minimized.

@NiklasMM

NiklasMM Aug 10, 2017
Contributor

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.

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

This comment has been minimized.

@NiklasMM

NiklasMM Aug 10, 2017
Contributor

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

@damngamerz damngamerz force-pushed the damngamerz:docgrammarbear branch from 4983264 to f78e22d Aug 11, 2017
make_docstring(main_desc='Il monte s’il veut.\n'),
{'locale': 'fr',
'languagetool_disable_rules': 'FRENCH_WHITESPACE'})

@damngamerz damngamerz force-pushed the damngamerz:docgrammarbear branch 2 times, most recently from a4a1066 to 94f6f1b Aug 11, 2017
# which was breaking this test case.
test_language_french = unittest.skipIf(
platform.system() == 'Windows',
"language-check fails this test on windows")(

This comment has been minimized.

@gitmate-bot

gitmate-bot Aug 12, 2017
Collaborator

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'),
@damngamerz damngamerz force-pushed the damngamerz:docgrammarbear branch 2 times, most recently from 51c80c1 to 3918169 Aug 12, 2017
@damngamerz damngamerz force-pushed the damngamerz:docgrammarbear branch from 3918169 to b2f13c6 Aug 14, 2017
@damngamerz damngamerz force-pushed the damngamerz:docgrammarbear branch 2 times, most recently from 369d4f8 to b86b53b Aug 15, 2017
This bear checks for spellings and grammatical mistakes
on the descriptions of documentation comments.
@damngamerz damngamerz force-pushed the damngamerz:docgrammarbear branch from b86b53b to 112fa7d Aug 15, 2017
@SanketDG
Copy link
Member

@SanketDG SanketDG commented Aug 16, 2017

ack 112fa7d

@SanketDG
Copy link
Member

@SanketDG SanketDG commented Aug 16, 2017

@rultor merge

@rultor
Copy link

@rultor rultor commented Aug 16, 2017

@rultor merge

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

@rultor rultor merged commit 112fa7d into coala:master Aug 16, 2017
6 of 9 checks passed
6 of 9 checks passed
ci/circleci CircleCI is running your tests
Details
continuous-integration/appveyor/branch Waiting for AppVeyor build to complete
Details
continuous-integration/travis-ci/push The Travis CI build is in progress
Details
codecov/project 100% (target 100%)
Details
continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
review/gitmate/commit No issues with this one - go ahead! :)
Details
review/gitmate/manual This commit was acknowledged.
Details
review/gitmate/pr All is well! :) (0 problems solved)
Details
@rultor
Copy link

@rultor rultor commented Aug 16, 2017

@rultor merge

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

@damngamerz damngamerz deleted the damngamerz:docgrammarbear branch Aug 16, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Linked issues

Successfully merging this pull request may close these issues.

None yet

6 participants
You can’t perform that action at this time.