Skip to content
This repository has been archived by the owner on Sep 15, 2021. It is now read-only.

**kwargs usage breaks generation for macros #158

Closed
thomasvl opened this issue Feb 21, 2019 · 0 comments
Closed

**kwargs usage breaks generation for macros #158

thomasvl opened this issue Feb 21, 2019 · 0 comments

Comments

@thomasvl
Copy link
Member

thomasvl commented Feb 21, 2019

Given:

def my_macro(name, a, b=[], c="blah", **kwargs):
    """Mumble

    Args:
      name: The name
      a: An a
      b: List of b
      c: A string
      **kwargs: The <a href="https://docs.bazel.build/versions/master/be/common-definitions.html#common-attributes-tests">common attributes for tests</a>.

    """
    pass

You get generated markdown of:

## my_macro

<pre>
my_macro(<a href="#my_macro-name">name</a>, <a href="#my_macro-a">a</a>, <a href="#my_macro-b">b</a>, <a href="#my_macro-c">c</a>, <a href="#my_macro-kwargs">kwargs</a>)
</pre>

Mumble

### Parameters

<table class="params-table">
  <colgroup>
    <col class="col-param" />
    <col class="col-description" />
  </colgroup>
  <tbody>
    <tr id="my_macro-name">
      <td><code>name</code></td>
      <td>
        required.
        <p>
          The name
        </p>
      </td>
    </tr>
    <tr id="my_macro-a">
      <td><code>a</code></td>
      <td>
        required.
        <p>
          An a
        </p>
      </td>
    </tr>
    <tr id="my_macro-b">
      <td><code>b</code></td>
      <td>
        required.
        <p>
          List of b
        </p>
      </td>
    </tr>
    <tr id="my_macro-c">
      <td><code>c</code></td>
      <td>
        optional. default is <code>[]</code>
        <p>
          A string
        </p>
      </td>
    </tr>
    <tr id="my_macro-kwargs">
      <td><code>kwargs</code></td>
      <td>
        optional. default is <code>"blah"</code>
      </td>
    </tr>
  </tbody>
</table>

Which renders to:


my_macro

my_macro(name, a, b, c, kwargs)

Mumble

Parameters

name required.

The name

a required.

An a

b required.

List of b

c optional. default is []

A string

kwargs optional. default is "blah"

What's worth noting here:

  1. b, c, and kwargs have shifted default values.
  2. b is listed as required, but it has a default, like to do with the previous issue of displaying wrong defaults.
  3. kwargs is missing its description.

If you change the **kwargs in the Args section to just kwargs, then description is displayed, but the other issues still apply.

bazel-io pushed a commit to bazelbuild/bazel that referenced this issue Feb 25, 2019
Progress toward bazelbuild/skydoc#158

RELNOTES: None.
PiperOrigin-RevId: 235574880
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants