Add default aesthetic values to geom docs

[steveharoz]

A common problem, especially for beginner users, is that you make a plot using default aesthetic values, but then you want to adjust them by a relative amount. For example, you make a plot with geom_point(), but you want the points to be 50% larger. Is the default size 1? 0.01 (proportion of the chart size)? 10 (pixels)? If you don't know the default value, it's tough to know even what order of magnitude to set the new value to.

So, this update adds the default value next to each aesthetic listed in the docs.

It'll impact every geom's documentation, so I wanted to discuss it here before pushing all the generated .RD files.

Stylized values

How values are displayed varies by the aesthetic and type:

• Color and fill: The background color of the text is set to the value. The foreground text color has the extreme opposite luminance (white for dark colors and black for light colors). NA and "transparent" are handled specially.
• Shapes show both the number and the name. If one is provided, it will look up the other. E.g., 19 or "circle"
• Linetypes show both the number and the name. If one is provided, it will look up the other. E.g., 1 or "solid"
• Other strings have quotes added around them.
• Anything else is shown as a code block. E.g., ~after_stat(x)

Screenshot from RStudio:

[thomasp85]

I like this! ❤️

[teunbrand]

I also think this is great!

Any reason not to?

Technically, one can change the defaults with update_geom_defaults() at which point the docs no longer reflect the state. However, I think the usefulness of this PR outweighs that consideration.

How should the default value to appear?

I'm a fan of the low clutter option. Maybe the line on top should just read

geom_foobar() understands the following aesthetics. Required aesthetics are displayed in bold and optional aesthetics list their default values.

A few other things to consider:

• The group's default is -1, unless a discrete mapping prompts a grouping. I don't think this is a convenient place to display this and the group's link already explains this.
• Should character defaults be displayed with quotes? E.g. "black" instead of black, unless NA.
• How are aesthetics with delayed evaluation displayed? For example, stat_qq() has x = after_stat(x),

[smouksassi]

how would the user know the "units" of say size:1.5
and would it be useful to remind users that shapes can be numeric or specific strings?
shape: 19 / "circle"

[teunbrand]

@smoukassi Most of such details are in the exact vignette that the bottom line refers to, so I think the verbosity is good as-is.

[steveharoz]

I used @teunbrand's suggestion for the text at the top. Thanks.

I agree with @smouksassi, at least in part. Sure, people can look it up the details, but I remember really struggling with this stuff as a beginner. So now the default value shows as both a number and a string. Which ever one is given, it will look up the other. And it should gracefully handle non-typical values that it can't look up. See the new screenshot at the top.

[teunbrand]

Sorry for nitpicking this, but alpha(x, NA) is not equivalent to alpha(x, 1). Using alpha(x, NA) preserves the alpha channel, whereas alpha(x, 1) does not.

library(scales)
alpha("#FF000088", NA)
#> [1] "#FF000088"
alpha("#FF000088", 1)
#> [1] "#FF0000FF"

^{Created on 2023-10-27 with reprex v2.0.2}

[teunbrand]

The spirit of the PR was included as part of #6285, so I'm closing this PR in favour of the other.