Page MenuHomePhabricator

Lint test to match function signature and documentation
Closed, ResolvedPublic

Description

In the process of code review with some of the recent patches to Pywikibot I realized that we don't have a lint checker that would look at the function's signature (i.e. parameter names) and compares with the function documentation. We should set up such a test.

Event Timeline

@Xqt does flake8 even have support for this? I know it supports finding unused arguments and it supports some checks on doc strings but I am not familiar enough with flake8 to know if it supports the propose idea of the current Task.

@Huji: I didn’t found a flake8 package for it but deep source can do it for us: https://deepsource.io/gh/ankitdobhal/pywikibot/issue/PYL-E1123/occurrences

But this only checks the code and not the documentation I guess.

Xqt triaged this task as Medium priority.Mar 19 2021, 7:44 AM

Probably https://pypi.org/project/darglint/ would be appropriate for this

Does not work currently.
We use epytext format for docstrings but darglint supports sphinx.

Change 673520 had a related patch set uploaded (by Xqt; owner: Xqt):
[pywikibot/core@master] [tests] Add darglint to flake8 tests

https://gerrit.wikimedia.org/r/673520

Change 673520 abandoned by Xqt:

[pywikibot/core@master] [tests] Add darglint to flake8 tests

Reason:

https://phabricator.wikimedia.org/T278046

https://gerrit.wikimedia.org/r/673520

@atagar: are you willing to takeover this task?

Hi Xqt. It's a bit unclear to me what the task is...

lint checker that would look at the function's signature (i.e. parameter names) and compares with the function documentation

Does this mean this aims for a lint check for the following?

def my_function(my_arg):
  """
  Some neat stuff.

  :param wrong_name: blah
  """

If so I'd be happy to take a look, but I'd think Sphinx would already exhibit a warning for that.

Hi Xqt. It's a bit unclear to me what the task is...

lint checker that would look at the function's signature (i.e. parameter names) and compares with the function documentation

Does this mean this aims for a lint check for the following?

def my_function(my_arg):
  """
  Some neat stuff.

  :param wrong_name: blah
  """

If so I'd be happy to take a look, but I'd think Sphinx would already exhibit a warning for that.

Yes I meant this shown by your example. Sphinx does not give a warning for that (or it is deactivated and nitpick option must be set). Darglint tests it but there are so many false positives or code to be changed that I've given up with my patch recently.

Change 673520 restored by Xqt:

[pywikibot/core@master] [tests] Add darglint to flake8 tests

https://gerrit.wikimedia.org/r/673520

Xqt claimed this task.

Change 673520 merged by jenkins-bot:

[pywikibot/core@master] [tests] Add darglint to flake8 tests

https://gerrit.wikimedia.org/r/673520