First pass on grammar for \arguments

Author: MichaelChirico

man/mergelist.Rd

@@ -17,9 +17,9 @@
   \item{l}{ \code{list} of \code{data.table}s to merge. }
   \item{on}{ \code{character} vector of column names to merge on; when missing, the \code{\link{key}} of the \emph{join-to} table is used (see Details). }
   \item{cols}{ Optional \code{list} of \code{character} column names corresponding to tables in \code{l}, used to subset columns during merges. \code{NULL} means all columns, all tables; \code{NULL} entries in a list means all columns for the corresponding table. }
-  \item{how}{ \code{character} scalar, controls how to merge tables. Allowed values are \code{"left"} (default), \code{"inner"}, \code{"full"}, \code{"right"}, \code{"semi"}, \code{"anti"}, \code{"cross"}. See Details. }
-  \item{mult}{ \code{character} scalar, controls how to proceed when multiple rows in \emph{join-to} table match to the row in \emph{join-from} table. Allowed values are \code{"error"}, \code{"all"}, \code{"first"}, \code{"last"}. Default depends on \code{how}, described in \emph{details} below. See examples on how to detect duplicated matches. Using \code{"all"} is recommended together with \code{join.many=FALSE}, unless rows explosion or cartesian product are intended. }
-  \item{join.many}{ \code{logical}, defaults to \code{getOption("datatable.join.many")}, which is \code{TRUE} by default; when \code{FALSE} and \code{mult="all"}, then extra check is made to ensure no \emph{many-to-many} matches exist between tables, and if they exist, then exception is raised. Works similarly to \code{allow.cartesian} option in \code{[.data.table} but is more strict. An option \code{"datatable.join.many"} controls that globally for \code{mergelist} and \code{[.data.table}. }
+  \item{how}{ Character string, controls how to merge tables. Allowed values are \code{"left"} (default), \code{"inner"}, \code{"full"}, \code{"right"}, \code{"semi"}, \code{"anti"}, and \code{"cross"}. See Details. }
+  \item{mult}{ Character string, controls how to proceed when multiple rows in the \emph{join-to} table match to the row in the \emph{join-from} table. Allowed values are \code{"error"}, \code{"all"}, \code{"first"}, \code{"last"}. The default value depends on \code{how}; see Details. See Examples for how to detect duplicated matches. When using \code{"all"}, we recommend specifying \code{join.many=FALSE} as a precaution to prevent unintended explosion of rows. }
+  \item{join.many}{ \code{logical}, defaulting to \code{getOption("datatable.join.many")}, which is \code{TRUE} by default; when \code{FALSE} and \code{mult="all"}, an error is thrown when any \emph{many-to-many} matches are detected between pairs of tables. This is essentially a stricter version of the \code{allow.cartesian} option in \code{\link{[.data.table}}. Note that the option \code{"datatable.join.many"} also controls the behavior of joins in \code{[.data.table}. }
 }
 \details{
   Function should be considered experimental. Users are encouraged to provide feedback in our issue tracker.