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

Allow documentation for **kwargs in wrappers OR turn off lint warning. #768

Closed
aiuto opened this issue Jan 24, 2020 · 1 comment · Fixed by #772
Closed

Allow documentation for **kwargs in wrappers OR turn off lint warning. #768

aiuto opened this issue Jan 24, 2020 · 1 comment · Fixed by #772

Comments

@aiuto
Copy link
Contributor

aiuto commented Jan 24, 2020

Consider this wrapper method:

# buildifier: disable=function-docstring-args
def license(name, license_kinds = None, license_kind = None, copyright_notice = None, **kwargs):
    """Wrapper for license rule.

    Args:
      name: str target name.
      license_kinds: list(label) list of license_kind targets.
      license_kind: label a single license_kind. Only one of license_kind or license_kinds may
                    be specified
      copyright_notice: str Copyright notice associated with this package.
    """

First of all, the parsing must be broken, because (without the disable line) I see the lint warning

Argument "**kwargs" is not documented. 
 https://github.com/bazelbuild/buildtools/blob/master/WARNINGS.md#function-docstring-args

I added this to the docstring
kwargs: additional args

And still get the above warning, plus

Argument "kwargs" is documented but doesn't exist in the function signature. 
  https://github.com/bazelbuild/buildtools/blob/master/WARNINGS.md#function-docstring-args

This is a no win.

Suggested solution: Allow this in the docstring
kwargs: [forwarded to <other rule name>]

The magical [fowarded to ...] would tell lint not to complain about it.
The could be used by Stardoc to pull up the definitions from the underlying rule, so we could document the wrapper appropriately.

@vladmos
Copy link
Member

vladmos commented Jan 25, 2020

You should be able to document kwargs as **kwargs (with two asterisks), because just kwargs refers to a non-existing positional/keyword argument. In general, if the signature looks like

def f(foo, *bar, **baz):

you should define exactly the same literals in the documentation:

Args:
  foo: ...
  *bar: ...
  **baz: ...

I don't see whether the magical [fowarded to ...] is useful, Buildifier doesn't analyze the documentation of each argument, it just makes sure it exists.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants