Unclear documentation: geom_label, geom_text, and others: position argument

[rcragun]

Problem

The documentation for geom_label() and geom_text() (and many other geoms) is unclear about the position argument. It says, “Position adjustment, either as a string, or the result of a call to a position adjustment function”. Nothing in that description is helpful to a user like me. I am left wondering what strings are options and what a “position adjustment function” is.

Additional issues

Sure, there is an online reference that explains this if the user knows to look for it and knows where to look within it, but if that is something the user needs to know, it needs to be documented. The user should also not have to already know the names of the position functions to be able to get to their documentation from the position argument of a geom documentation page.

I also get that it is not sufficient to simply list off some strings and functions because someone could make a custom position function. However, this does not justify giving no information at all about existing functions that are built-in to the ggplot2 package (and their string handles, I suppose) or on the conditions that custom position functions must meet.

Proposed solution:

The documentation should

1. list every available position string and position adjustment function that is built-in to the ggplot2 package
2. state that custom position adjustment functions may also be used
3. describe exactly what a “position adjustment function” is (i.e. what conditions would my own custom function have to satisfy?)

On points 1 and 3, if the implementation is likely to change over time, it may be best to link to another page of documentation that lists the current functions and strings (and what is a valid position function) in order to avoid having to update the documentation for many geoms every time the position options change. This content has already been written and included in the reference manual, so it only needs to be ported into the documentation somewhere (maybe at the package level).

[hadley]

I don't think there's a need to list every position adjustment (since some a pretty esoteric), but we could certainly do better here. We may also want to think about how to provide the same core description with a list of different position adjustments, since the usual ones vary based on the geom.