update docs

R/tnrs.R

@@ -4,22 +4,29 @@
 ##' potential matches for these names to known taxa in the Open Tree
 ##' Taxonomy.
 ##'
-##' This service uses taxonomic contexts to disambiguate homonyms and
-##' misspelled names; a context may be specified using the
-##' \code{context_name} argument. If no context is specified, then the
-##' context will be inferred (i.e., the shallowest taxonomic context
-##' that contains all unambiguous names in the input). Taxonomic
-##' contexts are uncontested higher taxa that have been selected to
-##' allow limits to be applied to the scope of TNRS searches
-##' (e.g. 'match names only within flowering plants'). Once a context
-##' has been identified (either user-specified or inferred), all taxon
-##' name matches will performed only against taxa within that
-##' context. For a list of available taxonomic contexts, see
-##' \code{\link{tnrs_contexts}}.
+##' This service uses taxonomic contexts to disambiguate homonyms and misspelled
+##' names; a context may be specified using the \code{context_name} argument.
+##' The default value for \code{context_name} is "All life". If no context is
+##' specified (i.e., \code{context_name} is set to \code{NULL}), then the
+##' context will be inferred (i.e., the shallowest taxonomic context that
+##' contains all unambiguous names in the input). Taxonomic contexts are
+##' uncontested higher taxa that have been selected to allow limits to be
+##' applied to the scope of TNRS searches (e.g. 'match names only within
+##' flowering plants'). Once a context has been identified (either
+##' user-specified or inferred), all taxon name matches will performed only
+##' against taxa within that context. For a list of available taxonomic
+##' contexts, see \code{\link{tnrs_contexts}}.
 ##'
 ##' A name is considered unambiguous if it is not a synonym and has
 ##' only one exact match to any taxon name in the entire taxonomy.
 ##'
+##' When the name search returns multiple matches, the taxon with the highest
+##' match score is returned. If the name returned is not the one you intended,
+##' you can use the \code{inspect} function to check the other taxa returned by
+##' your search. The
+##' \href{https://docs.ropensci.org/rotl/articles/rotl.html#how-to-change-the-ott-ids-assigned-to-my-taxa}{Getting
+##' Started vignette} has more information on how to do this.
+##'
 ##' Several functions listed in the \sQuote{See also} section can be
 ##' used to inspect and manipulate the object generated by this
 ##' function.