Document commonly used optional arguments

Functions that take take `id` or `web_history` now
have those arguments documented and provided in the signature
(so they are tab-completable).

Functions that use `...` for API calls ahve link to API docs

This closes #48

R/entrez_fetch.r

@@ -14,8 +14,10 @@
 #'@param web_history A web_history object 
 #'@param rettype character Format in which to get data (eg, fasta, xml...)
 #'@param retmode character Mode in which to receive data, defaults to 'text'
-#'@param \dots character Additional terms to add to the request
 #'@param config vector configuration options passed to httr::GET
+#'@param \dots character Additional terms to add to the request, see NCBI
+#'documentation linked to in referenes for a complete list
+#'@references \url{http://www.ncbi.nlm.nih.gov/books/NBK25499/#_chapter4_EFetch_} 
 #'@param parsed boolean should entrez_fetch attempt to parse the resulting 
 #' file. Only works with rettype="xml" at present
 #'@seealso \code{\link[httr]{config}} for available configs

R/entrez_link.r

@@ -28,14 +28,15 @@
 #'   \item prlinks. As 'llinks' but returns only the primary external link for
 #'   each ID.
 #'}
-#'@param \dots character Additional terms to add to the request
+#'@param \dots character Additional terms to add to the request, see NCBI
+#'documentation linked to in referenes for a complete list
 #'@param config vector configuration options passed to httr::GET  
 #'@seealso \code{\link[httr]{config}} for available configs 
 #'@seealso  \code{entrez_db_links}
 #'@return An elink object containing the data defined by the \code{cmd} argument
 #'@return file XMLInternalDocument xml file resulting from search, parsed with
 #'\code{\link{xmlTreeParse}}
-#'@references http://www.ncbi.nlm.nih.gov/books/NBK25499/#_chapter4_ELink_
+#'@references \url{http://www.ncbi.nlm.nih.gov/books/NBK25499/#_chapter4_ELink_}
 #'@importFrom XML xmlToList
 #' @examples
 #' \donttest{

R/entrez_post.r

@@ -7,20 +7,21 @@
 #'@param id vector with unique ID(s) for reacods in database \code{db}. 
 #'@param web_history A web_history object. Can be used to add to additional
 #' identifiers to an existing web environment on the NCBI 
-#'@param \dots character Additional terms to add to the request 
+#'@param \dots character Additional terms to add to the request, see NCBI
+#'documentation linked to in referenes for a complete list
 #'@param config vector configuration options passed to httr::GET  
+#'@references \url{http://www.ncbi.nlm.nih.gov/books/NBK25499/#_chapter4_EPost_} 
 #'@seealso \code{\link[httr]{config}} for available configs 
 #'@importFrom XML xmlTreeParse
 #' @examples
 #'\dontrun{  
 #' so_many_snails <- entrez_search(db="nuccore", 
 #'                       "Gastropoda[Organism] AND COI[Gene]", retmax=200)
 #' upload <- entrez_post(db="nuccore", id=so_many_snails$ids)
-#' cookie <- upload$WebEnv
-#' first <- entrez_fetch(db="nuccore", rettype="fasta", WebEnv=cookie,
-#'                       query_key=upload$QueryKey, retmax=10)
-#' second <- entrez_fetch(db="nuccore", file_format="fasta", WebEnv=cookie,
-#'                        query_key=upload$QueryKey, retstart=10, retmax=10)
+#' first <- entrez_fetch(db="nuccore", rettype="fasta", web_history=upload,
+#'                       retmax=10)
+#' second <- entrez_fetch(db="nuccore", file_format="fasta", web_history=upload,
+#'                        retstart=10, retmax=10)
 #'}
 
 entrez_post <- function(db, id=NULL, web_history=NULL, config=NULL, ...){

R/entrez_search.r

@@ -10,8 +10,9 @@
 #' later calls to the NCBI
 #'@param retmode character One of json (default) or xml. This will make no
 #' difference in most cases.
+#'@param \dots character Additional terms to add to the request, see NCBI
+#'documentation linked to in referenes for a complete list
 #'@param config vector configuration options passed to httr::GET  
-#'@param \dots character Additional terms to add to the request 
 #'@seealso \code{\link[httr]{config}} for available configs 
 #'@seealso \code{\link{entrez_db_searchable}} to get a set of search fields that
 #' can be used in \code{term} for any base
@@ -24,10 +25,11 @@
 #'\code{\link[XML]{xmlTreeParse}} or, if \code{retmode} was set to json a list
 #' resulting from the returned JSON file being parsed with
 #' \code{\link[jsonlite]{fromJSON}}.
-#' @examples
+#'@references \url{http://www.ncbi.nlm.nih.gov/books/NBK25499/#_chapter4_ESearch_} 
+#'@examples
 #' \dontrun{
 #'    query <- "Gastropoda[Organism] AND COI[Gene]"
-#'    web_env_search <- entrez_search(db="nuccore", query, usehistory="y")
+#'    web_env_search <- entrez_search(db="nuccore", query, use_history=TRUE)
 #'    cookie <- web_env_search$WebEnv
 #'    qk <- web_env_search$QueryKey 
 #'    snail_coi <- entrez_fetch(db = "nuccore", WebEnv = cookie, query_key = qk,

R/entrez_summary.r

@@ -20,11 +20,11 @@
 #'@param web_history A web_history object 
 #'@param always_return_list logical, return a list  of esummary objects even
 #'when only one ID is provided.
-#'@param \dots character Additional terms to add to the request. Requires either
-#'   id (unique id(s) for records in a given database) or WebEnv (a character
-#'   containing a cookie created by a previous entrez query).
+#'@param \dots character Additional terms to add to the request, see NCBI
+#'documentation linked to in referenes for a complete list
 #'@param config vector configuration options passed to \code{httr::GET}
 #'@param version either 1.0 or 2.0 see above for description
+#'@references \url{http://www.ncbi.nlm.nih.gov/books/NBK25499/#_chapter4_ESummary_} 
 #'@seealso \code{\link[httr]{config}} for available configs 
 #'@seealso \code{\link{extract_from_esummary}} which can be used to extract
 #'elements from a list of esummary records

man/entrez_fetch.Rd

@@ -23,7 +23,8 @@ file. Only works with rettype="xml" at present}
 
 \item{config}{vector configuration options passed to httr::GET}
 
-\item{\dots}{character Additional terms to add to the request}
+\item{\dots}{character Additional terms to add to the request, see NCBI
+documentation linked to in referenes for a complete list}
 }
 \value{
 character string containing the file created
@@ -40,6 +41,9 @@ katipo <- "Latrodectus katipo[Organism]"
 katipo_search <- entrez_search(db="nuccore", term=katipo)
 kaitpo_seqs <- entrez_fetch(db="nuccore", id=katipo_search$ids, rettype="fasta")
 }
+\references{
+\url{http://www.ncbi.nlm.nih.gov/books/NBK25499/#_chapter4_EFetch_}
+}
 \seealso{
 \code{\link[httr]{config}} for available configs
 }

man/entrez_link.Rd

@@ -37,7 +37,8 @@ to discover databases that might have linked information (see examples).}
 
 \item{config}{vector configuration options passed to httr::GET}
 
-\item{\dots}{character Additional terms to add to the request}
+\item{\dots}{character Additional terms to add to the request, see NCBI
+documentation linked to in referenes for a complete list}
 }
 \value{
 An elink object containing the data defined by the \code{cmd} argument
@@ -61,7 +62,7 @@ set for the \code{cmd} argument. Printing the returned object lists the names
 }
 }
 \references{
-http://www.ncbi.nlm.nih.gov/books/NBK25499/#_chapter4_ELink_
+\url{http://www.ncbi.nlm.nih.gov/books/NBK25499/#_chapter4_ELink_}
 }
 \seealso{
 \code{\link[httr]{config}} for available configs

man/entrez_post.Rd

@@ -16,7 +16,8 @@ identifiers to an existing web environment on the NCBI}
 
 \item{config}{vector configuration options passed to httr::GET}
 
-\item{\dots}{character Additional terms to add to the request}
+\item{\dots}{character Additional terms to add to the request, see NCBI
+documentation linked to in referenes for a complete list}
 }
 \description{
 Post IDs to Eutils for later use
@@ -26,13 +27,15 @@ Post IDs to Eutils for later use
 so_many_snails <- entrez_search(db="nuccore",
                       "Gastropoda[Organism] AND COI[Gene]", retmax=200)
 upload <- entrez_post(db="nuccore", id=so_many_snails$ids)
-cookie <- upload$WebEnv
-first <- entrez_fetch(db="nuccore", rettype="fasta", WebEnv=cookie,
-                      query_key=upload$QueryKey, retmax=10)
-second <- entrez_fetch(db="nuccore", file_format="fasta", WebEnv=cookie,
-                       query_key=upload$QueryKey, retstart=10, retmax=10)
+first <- entrez_fetch(db="nuccore", rettype="fasta", web_history=upload,
+                      retmax=10)
+second <- entrez_fetch(db="nuccore", file_format="fasta", web_history=upload,
+                       retstart=10, retmax=10)
 }
 }
+\references{
+\url{http://www.ncbi.nlm.nih.gov/books/NBK25499/#_chapter4_EPost_}
+}
 \seealso{
 \code{\link[httr]{config}} for available configs
 }

man/entrez_search.Rd

@@ -20,7 +20,8 @@ difference in most cases.}
 \item{use_history}{locgical Return a web_history object for use in
 later calls to the NCBI}
 
-\item{\dots}{character Additional terms to add to the request}
+\item{\dots}{character Additional terms to add to the request, see NCBI
+documentation linked to in referenes for a complete list}
 }
 \value{
 ids integer Unique IDS returned by the search
@@ -45,7 +46,7 @@ a database name, then retrieves the XML document created by that query.
 \examples{
 \dontrun{
    query <- "Gastropoda[Organism] AND COI[Gene]"
-   web_env_search <- entrez_search(db="nuccore", query, usehistory="y")
+   web_env_search <- entrez_search(db="nuccore", query, use_history=TRUE)
    cookie <- web_env_search$WebEnv
    qk <- web_env_search$QueryKey
    snail_coi <- entrez_fetch(db = "nuccore", WebEnv = cookie, query_key = qk,
@@ -62,6 +63,9 @@ tax_fields$RANK
 entrez_search(db="taxonomy", term="Drosophila & Genus[RANK]")
 }
 }
+\references{
+\url{http://www.ncbi.nlm.nih.gov/books/NBK25499/#_chapter4_ESearch_}
+}
 \seealso{
 \code{\link[httr]{config}} for available configs
 

man/entrez_summary.Rd

@@ -21,9 +21,8 @@ when only one ID is provided.}
 
 \item{config}{vector configuration options passed to \code{httr::GET}}
 
-\item{\dots}{character Additional terms to add to the request. Requires either
-id (unique id(s) for records in a given database) or WebEnv (a character
-containing a cookie created by a previous entrez query).}
+\item{\dots}{character Additional terms to add to the request, see NCBI
+documentation linked to in referenes for a complete list}
 }
 \value{
 A list of esummary records (if multiple IDs are passed and
@@ -59,6 +58,9 @@ pop_ids = c("307082412", "307075396", "307075338", "307075274")
  extract_from_esummary(cv, "trait_set")[1:2]
  extract_from_esummary(cv, "gene_sort")
 }
+\references{
+\url{http://www.ncbi.nlm.nih.gov/books/NBK25499/#_chapter4_ESummary_}
+}
 \seealso{
 \code{\link[httr]{config}} for available configs