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

DocumentationAPI: Add `padding` #4557

Merged
merged 1 commit into from Aug 18, 2017

Conversation

@damngamerz
Member

damngamerz commented Jul 25, 2017

Add padding in DocstyleDefinition which
are now acquired from .coalang. Add
top_padding and bottom_padding which
automatically instantiate from
instantiate_padding in DocBaseClass. Add
supporting test cases.

Related to #4200

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!

@jayvdb

I see you have not add padding for all other languages.
But you make padding mandatory.
So this would break all languages without a padding in their style?

Show outdated Hide outdated coalib/bearlib/languages/documentation/DocstyleDefinition.py
Show outdated Hide outdated coalib/bearlib/languages/documentation/DocstyleDefinition.py
Show outdated Hide outdated coalib/bearlib/languages/documentation/DocBaseClass.py
@damngamerz

This comment has been minimized.

Show comment
Hide comment
@damngamerz

damngamerz Jul 26, 2017

Member

@jayvdb We can continue our discussion here.... As default.coalang will take care of the intended blank lines.
So for python I believe is that PEP-257 is old. Even we don't follow it's official multi line docstring. And I feel what we use here at coala is much better(which is an enhanced inherited version of PEP - 257 standards).
atm we don't have any mechanism to describe the docstring type. Is it normal function docstring or class function docstring?
so any ideas what can be top_padding and bottom_padding which can be applied to all docstrings in coala repo, coala-bears? my bets are on (0,1). As generally we need to have a blank line after the docstring(such as in class function).
Or if we don't implement this now, leave it as (0,0) cause this is a trivial task. And find some way to get docstring origin(function docstring, class function docstring....etc).

Member

damngamerz commented Jul 26, 2017

@jayvdb We can continue our discussion here.... As default.coalang will take care of the intended blank lines.
So for python I believe is that PEP-257 is old. Even we don't follow it's official multi line docstring. And I feel what we use here at coala is much better(which is an enhanced inherited version of PEP - 257 standards).
atm we don't have any mechanism to describe the docstring type. Is it normal function docstring or class function docstring?
so any ideas what can be top_padding and bottom_padding which can be applied to all docstrings in coala repo, coala-bears? my bets are on (0,1). As generally we need to have a blank line after the docstring(such as in class function).
Or if we don't implement this now, leave it as (0,0) cause this is a trivial task. And find some way to get docstring origin(function docstring, class function docstring....etc).

@jayvdb

All of the examples seem to be using padding (1, 1).

I re-iterate what Niklas has said at coala/coala-bears#1943 (comment) , you need to be creating your own scenarios which test different valid values, even if there is no defined style with that scenario of values.

Show outdated Hide outdated tests/bearlib/languages/documentation/DocBaseClassTest.py
Show outdated Hide outdated tests/bearlib/languages/documentation/DocumentationCommentTest.py
Show outdated Hide outdated ...lib/languages/documentation/documentation_extraction_testdata/doxygen.py
@jayvdb

This comment has been minimized.

Show comment
Hide comment
@jayvdb

jayvdb Jul 27, 2017

Member

So for python I believe is that PEP-257 is old.

No, you are wrong. On https://www.python.org/dev/peps/pep-0257/ , you can see it's status is "Active". It has not been replaced. It is maintained at https://github.com/python/peps/commits/master/pep-0257.txt
And https://github.com/pycqa/pydocstyle implements it. And there are vibrant discussions about the finer details of it, and pydocstyle allowing ignoring some of its rules to allow for alternative styles (and recently has a few extra rules to enforce other styles), but nobody dares say pep 257 is not the official style guide of Python.

And I feel what we use here at coala is much better(which is an enhanced inherited version of PEP - 257 standards).

Again, wrong.
What coala uses is not particularly good. The reason it is bad is because we have not undertaken a project to standardise the docstrings. No bears are enabled. The docstrings can contain anything. Only manual code review can catch problems. Your project is intended to solve that. Or we can work towards enabling PyDocStyleBear.
There is also a bug in QuotesBear which imposes a silly PEP 257 violation.
In fact Stefan and I were complaining about the bears bad behaviour recently on another patch very recently. We were asking for changes without realising that QuotesBear prohibited it.

atm we don't have any mechanism to describe the docstring type.

A design problem, for sure.

Member

jayvdb commented Jul 27, 2017

So for python I believe is that PEP-257 is old.

No, you are wrong. On https://www.python.org/dev/peps/pep-0257/ , you can see it's status is "Active". It has not been replaced. It is maintained at https://github.com/python/peps/commits/master/pep-0257.txt
And https://github.com/pycqa/pydocstyle implements it. And there are vibrant discussions about the finer details of it, and pydocstyle allowing ignoring some of its rules to allow for alternative styles (and recently has a few extra rules to enforce other styles), but nobody dares say pep 257 is not the official style guide of Python.

And I feel what we use here at coala is much better(which is an enhanced inherited version of PEP - 257 standards).

Again, wrong.
What coala uses is not particularly good. The reason it is bad is because we have not undertaken a project to standardise the docstrings. No bears are enabled. The docstrings can contain anything. Only manual code review can catch problems. Your project is intended to solve that. Or we can work towards enabling PyDocStyleBear.
There is also a bug in QuotesBear which imposes a silly PEP 257 violation.
In fact Stefan and I were complaining about the bears bad behaviour recently on another patch very recently. We were asking for changes without realising that QuotesBear prohibited it.

atm we don't have any mechanism to describe the docstring type.

A design problem, for sure.

Show outdated Hide outdated ...lib/languages/documentation/documentation_extraction_testdata/default.py
Show outdated Hide outdated ...lib/languages/documentation/documentation_extraction_testdata/default.py
Show outdated Hide outdated ...lib/languages/documentation/documentation_extraction_testdata/default.py
Show outdated Hide outdated ...lib/languages/documentation/documentation_extraction_testdata/default.py
Show outdated Hide outdated ...lib/languages/documentation/documentation_extraction_testdata/default.py
@damngamerz

This comment has been minimized.

Show comment
Hide comment
@damngamerz

damngamerz Jul 29, 2017

Member

@jayvdb As this PR is going to add the functionality of padding in the DocumentationAPI. Now we need to design a thing which will define types of docstring(module , function and class). which will later use this padding feature. Hence I think first we merge this one. And then defining type of docstring can be in another PR. As It's a bit trivial atm and needs a proper design.

Member

damngamerz commented Jul 29, 2017

@jayvdb As this PR is going to add the functionality of padding in the DocumentationAPI. Now we need to design a thing which will define types of docstring(module , function and class). which will later use this padding feature. Hence I think first we merge this one. And then defining type of docstring can be in another PR. As It's a bit trivial atm and needs a proper design.

Show outdated Hide outdated coalib/bearlib/languages/documentation/DocBaseClass.py
Show outdated Hide outdated coalib/bearlib/languages/documentation/DocBaseClass.py
Show outdated Hide outdated coalib/bearlib/languages/documentation/DocBaseClass.py
Show outdated Hide outdated coalib/bearlib/languages/documentation/DocBaseClass.py
Show outdated Hide outdated coalib/bearlib/languages/documentation/DocBaseClass.py
Show outdated Hide outdated coalib/bearlib/languages/documentation/DocBaseClass.py
Show outdated Hide outdated coalib/bearlib/languages/documentation/DocstyleDefinition.py
Show outdated Hide outdated coalib/bearlib/languages/documentation/DocstyleDefinition.py
Show outdated Hide outdated coalib/bearlib/languages/documentation/DocstyleDefinition.py
@jayvdb

jayvdb approved these changes Aug 3, 2017

changes to default.py look appropriate.

@gitmate-bot gitmate-bot added size/M and removed size/L labels Aug 4, 2017

Show outdated Hide outdated coalib/bearlib/languages/documentation/DocBaseClass.py
return self._function_padding
@property
def docstring_type_regex(self):

This comment has been minimized.

@NiklasMM

NiklasMM Aug 5, 2017

Contributor

Why do we need getters for all those members?

@NiklasMM

NiklasMM Aug 5, 2017

Contributor

Why do we need getters for all those members?

This comment has been minimized.

@damngamerz

damngamerz Aug 6, 2017

Member

As everything we are fetching from .coalang is a standard. And we don't want anyone to set those up manually. Hence setting them as getters :)
PS- Even the previous things like markers, comment's signature....etc we are fetching from .coalang are introduced in DocstyleDefinition as getters.

@damngamerz

damngamerz Aug 6, 2017

Member

As everything we are fetching from .coalang is a standard. And we don't want anyone to set those up manually. Hence setting them as getters :)
PS- Even the previous things like markers, comment's signature....etc we are fetching from .coalang are introduced in DocstyleDefinition as getters.

This comment has been minimized.

@NiklasMM

NiklasMM Aug 6, 2017

Contributor

hm, ok... since Python doesn't have private members, the whole concept is a bit useless. But if you want to do it like that it's fine.

@NiklasMM

NiklasMM Aug 6, 2017

Contributor

hm, ok... since Python doesn't have private members, the whole concept is a bit useless. But if you want to do it like that it's fine.

Show outdated Hide outdated coalib/bearlib/languages/documentation/DocstyleDefinition.py
Show outdated Hide outdated coalib/bearlib/languages/documentation/DocBaseClass.py
Show outdated Hide outdated coalib/bearlib/languages/documentation/DocstyleDefinition.py
Show outdated Hide outdated coalib/bearlib/languages/documentation/DocstyleDefinition.py
Show outdated Hide outdated coalib/bearlib/languages/documentation/DocBaseClass.py
@NiklasMM

@damngamerz sorry this took so long. I'm beginning to like the overall design now 👍

Please have a look at my comments once more.

Show outdated Hide outdated coalib/bearlib/languages/documentation/DocstyleDefinition.py
Show outdated Hide outdated coalib/bearlib/languages/documentation/DocstyleDefinition.py
Show outdated Hide outdated coalib/bearlib/languages/documentation/DocstyleDefinition.py
*(int(padding) for padding in tuple(
docstyle_settings['class_padding'])))
except IndexError:
class_padding = cls.ClassPadding('', '')

This comment has been minimized.

@NiklasMM

NiklasMM Aug 9, 2017

Contributor

why is the default '', '' and not 0, 0?

@NiklasMM

NiklasMM Aug 9, 2017

Contributor

why is the default '', '' and not 0, 0?

This comment has been minimized.

@damngamerz

damngamerz Aug 10, 2017

Member

because 0, 0 will mean that official defined padding is 0, 0. So better leave the defaults to be '', ''

@damngamerz

damngamerz Aug 10, 2017

Member

because 0, 0 will mean that official defined padding is 0, 0. So better leave the defaults to be '', ''

Show outdated Hide outdated coalib/bearlib/languages/documentation/DocumentationExtraction.py
Show outdated Hide outdated coalib/bearlib/languages/documentation/DocumentationExtraction.py
Show outdated Hide outdated coalib/bearlib/languages/documentation/DocumentationExtraction.py
Show outdated Hide outdated coalib/bearlib/languages/documentation/DocumentationExtraction.py
@@ -186,13 +238,38 @@ def load(cls, language: str, docstyle: str, coalang_dir=None):
metadata = cls.Metadata(*(str(docstyle_settings.get(req_setting, ''))
for req_setting in metadata_settings))
try:
class_padding = cls.ClassPadding(
*(int(padding) for padding in tuple(

This comment has been minimized.

@NiklasMM

NiklasMM Aug 9, 2017

Contributor

In your previous comment you said that docstyle_settings['class_padding'] is a string like "1, 0", if this is true, tuple("1, 0") will be ("1", ",", " ", "0"), which int will choke on. Rather use docstyle_settings['class_padding'].split(",")

Also I'm wondering why this isn't caught by tests.

@NiklasMM

NiklasMM Aug 9, 2017

Contributor

In your previous comment you said that docstyle_settings['class_padding'] is a string like "1, 0", if this is true, tuple("1, 0") will be ("1", ",", " ", "0"), which int will choke on. Rather use docstyle_settings['class_padding'].split(",")

Also I'm wondering why this isn't caught by tests.

This comment has been minimized.

@damngamerz

damngamerz Aug 10, 2017

Member

Hmm now even I m wondering the same. You are correct about tuple('1,0') will be ("1", ",", " ", "0") but what I figured out is docstyle_settings is a Setting object. Now when I do tuple(docstyle_settings['class_padding'].value) gives me ("1", ",", " ", "0") but when I only do tuple(docstyle_settings['class_padding']) gives me ('1', '0')(some magic 😛 I m guessing it has to do something with the Setting object). So I think let it be that way.

@damngamerz

damngamerz Aug 10, 2017

Member

Hmm now even I m wondering the same. You are correct about tuple('1,0') will be ("1", ",", " ", "0") but what I figured out is docstyle_settings is a Setting object. Now when I do tuple(docstyle_settings['class_padding'].value) gives me ("1", ",", " ", "0") but when I only do tuple(docstyle_settings['class_padding']) gives me ('1', '0')(some magic 😛 I m guessing it has to do something with the Setting object). So I think let it be that way.

This comment has been minimized.

@NiklasMM

NiklasMM Aug 14, 2017

Contributor

uh no, please investigate

@NiklasMM

NiklasMM Aug 14, 2017

Contributor

uh no, please investigate

This comment has been minimized.

@damngamerz

damngamerz Aug 14, 2017

Member

I see why it's like that

class Setting(StringConverter):

Setting offers common data type conversions. It has list_delimeters for list/tuple conversion. That's why we are getting ('1', '0') while doing tuple(docstyle_settings['class_padding']) 🎉

@damngamerz

damngamerz Aug 14, 2017

Member

I see why it's like that

class Setting(StringConverter):

Setting offers common data type conversions. It has list_delimeters for list/tuple conversion. That's why we are getting ('1', '0') while doing tuple(docstyle_settings['class_padding']) 🎉

This comment has been minimized.

@NiklasMM

NiklasMM Aug 15, 2017

Contributor

Wow, talk about overengineering.... anyway... it's ok then

@NiklasMM

NiklasMM Aug 15, 2017

Contributor

Wow, talk about overengineering.... anyway... it's ok then

Show outdated Hide outdated tests/bearlib/languages/documentation/DocBaseClassTest.py
@NiklasMM

This comment has been minimized.

Show comment
Hide comment
@NiklasMM

NiklasMM Aug 15, 2017

Contributor

@damngamerz one last thing: The commit message needs an update: kind doesn't exist anymore

Contributor

NiklasMM commented Aug 15, 2017

@damngamerz one last thing: The commit message needs an update: kind doesn't exist anymore

@damngamerz

This comment has been minimized.

Show comment
Hide comment
@damngamerz

damngamerz Aug 15, 2017

Member

@NiklasMM Updated commit message 👍

Member

damngamerz commented Aug 15, 2017

@NiklasMM Updated commit message 👍

@NiklasMM

This comment has been minimized.

Show comment
Hide comment
@NiklasMM

NiklasMM Aug 18, 2017

Contributor

ack d53307c

Contributor

NiklasMM commented Aug 18, 2017

ack d53307c

DocumentationAPI: Add `padding` and `type`
Add `class_padding`, `function_padding` and
`docstring_position` in DocstyleDefinition
which are now acquired from `.coalang`. Add
`top_padding` and `bottom_padding` which is
automatically instantiated from
DocumentationExtraction. Add `docstring_type` in
DocumentationComment which will automatically
determine the type of docstring from
DocumentationExtraction. Add supporting test
cases.

Related to #4200
@SanketDG

This comment has been minimized.

Show comment
Hide comment
@SanketDG
Member

SanketDG commented Aug 18, 2017

ack 070a19e

@SanketDG

This comment has been minimized.

Show comment
Hide comment
@SanketDG
Member

SanketDG commented Aug 18, 2017

@rultor merge

@rultor

This comment has been minimized.

Show comment
Hide comment
@rultor

rultor Aug 18, 2017

Contributor

@rultor merge

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

Contributor

rultor commented Aug 18, 2017

@rultor merge

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

@rultor rultor merged commit 070a19e into coala:master Aug 18, 2017

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 This commit has no issues. :)
Details
review/gitmate/manual This commit was acknowledged.
Details
review/gitmate/pr This PR has no issues. :)
Details
@rultor

This comment has been minimized.

Show comment
Hide comment
@rultor

rultor Aug 18, 2017

Contributor

@rultor merge

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

Contributor

rultor commented Aug 18, 2017

@rultor merge

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

@damngamerz damngamerz deleted the damngamerz:blankline branch Aug 18, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment