Can I document multiple parameters at once?

[schloerke]

In roxygen, we can say

# @param min_height,max_height,max_height_full_screen Any valid [CSS length
#   unit][htmltools::validateCssUnit()].

which documents min_height, max_height, and max_height_full_screen all in a single line.

Is this possible with numpydoc / supported by quartodoc?

[machow]

Ah I was just talking to @juliasilge about this. No, I don't think so--a common approach is to dynamically insert repeated descriptions :/.

def docwrapper(f):
    f.__doc__ = f.__doc__.format(a = "some repeated description")
    return f

@docwrapper
def my_func(a):
    """My function

    Parameters
    ------------
    a:
        {a}
    """

    return 1

# help(my_func)

Here's where it happens in py-shiny. Note that using functions like this requries using dynamic: true in quartodoc.

(it's maybe worth tracking some of the big roxygen things that are challenging in python. Since I know re-using a parameter description comes up often 😭)

[machow]

Wait, sorry -- I'm realizing you were asking another question: how do I give the same description to multiple parameters in a single function?

You can give the same description to parameters by separating them with a comma.

Currently, it looks like we just put each parameter on a separate row, even if they share a line in the docstring. It seems like we should consolidate them together on the same line instead of repeating.

Proposed behavior

• Each parameter can have separate type annotations. Let's keep first type annotation.
• Let's consider multiple parameters as using the same documentation if...
  • they are adjacent to eachother in the signature
  • their descriptions are identical
• Let's put them on the same line, separated by a comma

Example of current behavior

    def pin_versions_prune(
        self, name, n: "int | None" = None, days: "int | None" = None
    ):
        """Delete old versions of a pin.
        Parameters
        ----------
        name:
            Pin name.
        n, days:
            Pick one of `n` or `days` to choose how many versions to keep. `n = 3` will
            keep the last three versions; `days = 14` will keep all the versions in
            the last 14 days.
        """

New behavior

n and days are on the same line, similar to how pkgdown does it in e.g. slice():

[schloerke]

I'd like to even challenge the "same type" of

When two or more parameters have exactly the same type, shape, and description...

Ex: https://github.com/rstudio/bookdown/blob/52c31aa2fa44111b9ea67fdc4004f0ecd036c20f/R/ebook.R#L6-L9

#' @param fig_width,fig_height,dev,fig_caption Figure options (width, height,
#'   the graphical device, and whether to render figure captions).
#' @param number_sections Whether to number sections.
#' @param toc,toc_depth Whether to generate a table of contents, and its depth.

fig_width, fig_height are matching, but do not match dev or fig_caption.

toc is a bool and toc_depth is an int.

I can see the argument against this inconsistent documentation. So it may not be the best to adopt.

---

I'm happy with the comma for params with matching shape. Thank you!

@inheritParams functionality would also be great!

[machow]

Oh, good point on the types potentially being different. I'm not quite sure what might be a good option, then. I could see us leaving off types if they're different? I guess it's an issue of not repeating descriptions vs having different types. I do like how pkgdown let's you put them on the same line... 🤔