Explain how to fix fill guide for points with filled shapes

R/geom-point.R

@@ -85,6 +85,13 @@
 #' ggplot(mtcars, aes(wt, mpg)) +
 #'   geom_point(shape = 21, colour = "black", fill = "white", size = 5, stroke = 5)
 #'
+#' # The default shape used in legends is not filled, so you will need to
+#' # override it in the guide in order to see the fill reflected in the legend
+#' ggplot(mtcars, aes(wt, mpg, fill = factor(carb), shape = factor(cyl), colour = factor(vs))) +
+#'   geom_point(size = 5, stroke = 1) +
+#'   scale_shape_manual(values = 21:25) +
+#'   scale_fill_ordinal(guide = guide_legend(override.aes = list(shape = 21)))
+#'
 #' \donttest{
 #' # You can create interesting shapes by layering multiple points of
 #' # different sizes

vignettes/ggplot2-specs.Rmd

@@ -251,6 +251,8 @@ ggplot(sizes, aes(size, stroke, size = size, stroke = stroke)) +
   scale_size_identity()
 ```
 
+Because most shapes are not filled, mapping the `fill` aesthetic of points is considered an advanced feature. Additional steps may be required to produce sensible results, such as overriding the shape used in the `fill` guide (refer to `geom_point()` for an example of this).
+
 ## Text
 
 ### Font family