Documentation fixes for `coord_radial()`.

[iangow]

1. The placement of "superseded" here seems misleading, as it sits next to geom_radial(), which actually supersedes geom_polar().

2. Is the behaviour of the last example (code below) doing what you want it to do? (There are points displayed outside the "plot area", for example.) Or is the intention to have something more like the image below (taken from a Plotnine example here).

3. The examples don't fully exercise geom_radial(). I collected some examples (for Plotnine) here. I understand that might be too elaborate for the documentation.

ggplot(mtcars, aes(disp, mpg)) +
  geom_point() +
  coord_radial(
    start = -0.4 * pi,
    end = 0.4 * pi, inner.radius = 0.3,
    thetalim = c(200, 300),
    rlim = c(15, 30),
  )

[teunbrand]

Thanks for the report! With regards to your points;

1. Yes it is a bit unfortunate, but that is how pkgdown handles the reference and there isn't a lot we can do aside from removing it altogether.
2. Yes the behaviour of the code is correct. It can be debated whether coord_radial(clip = "on") should be the default, but we're explicitly setting zoom-limits without censoring the data, so you'd expect out-of-bounds points to show up.
3. Can you tell us more what explictly what you were expect but are not seeing? Some windrose examples maybe (?), as that seemed to be the topic of the linked page.

[teunbrand]

I've posed the pkgdown part here: r-lib/pkgdown#2992

[iangow]

Thanks for the report! With regards to your points;

1. Yes it is a bit unfortunate, but that is how pkgdown handles the reference and there isn't a lot we can do aside from removing it altogether.

Can you flip the order so that coord_radial() sits the left of coord_polar()? (Not sure why I typed geom_polar() before.) That would convey the right intent.

3. Yes the behaviour of the code is correct. It can be debated whether coord_radial(clip = "on") should be the default, but we're explicitly setting zoom-limits without censoring the data, so you'd expect out-of-bounds points to show up.

OK. Good to know. Perhaps a second example with coord_radial(clip = "on") would make this clearer?

4. Can you tell us more what explictly what you were expect but are not seeing? Some windrose examples maybe (?), as that seemed to be the topic of the linked page.

Not sure. Maybe I should work up a couple of examples to propose. Let me get back to you. (The linked page was a "demo page" for a pull request I filed for Plotnine.)