Which arguments need to be specified w/i `extra_params` for a new `ggproto`

Out of curiosity, is there any documentation on which parameters need to be defined inside extra_params for a ggplot2::ggproto object?

My initial thought was that it could be the parameters defined within the argument params of a ggplot2::layer(), but this is not true.

If you look at the extra_params of the GeomRibbon, for example, I would guess that only the parameters that are not explicitly included in the respective draw_group() function call must be included. For the GeomRibbon example:

• extra_params includes "orientation", which is probably addressed by params$extra_params w/i setup_data(),
• whereas extra_params does not include"outline.type", which is directly handed over to the function call draw_group().

A lot of the finer details of ggplot2 extension documentation are just comments in the source code, or the source code itself. For the extra_params field, it reads:

  # Most parameters for the geom are taken automatically from draw_panel() or
  # draw_groups(). However, some additional parameters may be needed
  # for setup_data() or handle_na(). These can not be imputed automatically,
  # so the slightly hacky "extra_params" field is used instead. By
  # default it contains `na.rm`

So indeed, most extra parameters are implied by the formals of the draw_panel and draw_group methods of ggproto classes.

The only place where it is used is the parameters() method of Geom and Stat classes.

This parameters() method itself is used in 3 places:

1. The Geom$draw_layer() method, where it is used to determine the parameters to pass on to the draw_panel() method.
2. The Stat$compute_layer() method, where it serves the same purpose.
3. The layer() function to check if the input are valid parameters.

So to answer your question, you should put any parameters there that aren't used in any of the draw_{panel/group} or compute_{panel/group} methods, but don't want layer() to give a warning about.