Documentation of arguments to `guide_axis` is unclear

[jarauh]

1. Apparently, order has to be numeric. However, this is not checked. Passing a character simply gives a warning ("NAs introduced by coercion").
2. There is no example of order nor of position.

I tried to add a secondary axis on the same side as the primary axis as follows:

ggplot(mtcars, aes(hp, mpg)) +
  geom_point() +
  scale_y_continuous(
    sec.axis = sec_axis(trans = ~ 235.215 / ., name = "l/100 km",
                        guide = guide_axis(order = 2, position = "left")))

This leads to a warning: "Discarding guide on merge. Do you have more than one guide with the same position?" And the secondary axis is not drawn. So it seems that I did not fully understand the use of order and position yet...

[jarauh]

See also: https://github.com/tidyverse/ggplot2/issues/4650#issuecomment-1214136938. Where it is suggested, that the primary axis should automatically take the opposite position of the secondary axis.

[teunbrand]

I'll incorporate an explicit type and length check for the order argument in #4879. Though I think the order argument only matters for axis guides when there are multiple guides for the same position. That makes the guide_axis() documentation a bit weird.