From ec6471491447ea51325b36f7cc7c9053ff6c3a89 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Herv=C3=A9=20Pag=C3=A8s?= <hpages.on.github@gmail.com>
Date: Wed, 17 Apr 2024 11:09:05 -0700
Subject: [PATCH] Some tweaks to UCSC.api.url() and its man page

---
 DESCRIPTION              |  2 +-
 R/UCSC.api.url.R         | 14 +++++++-------
 man/UCSC.api.url.Rd      | 41 +++++++++++++++++++++++-----------------
 vignettes/UCSC.utils.Rmd |  4 ++--
 4 files changed, 34 insertions(+), 27 deletions(-)

diff --git a/DESCRIPTION b/DESCRIPTION
index 3c883a3..cd0ba29 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -10,7 +10,7 @@ biocViews: Infrastructure, GenomeAssembly, Annotation, GenomeAnnotation,
 	DataImport
 URL: https://bioconductor.org/packages/UCSC.utils
 BugReports: https://github.com/Bioconductor/UCSC.utils/issues
-Version: 0.99.6
+Version: 0.99.7
 License: Artistic-2.0
 Encoding: UTF-8
 Authors@R: person("Hervé", "Pagès", role=c("aut", "cre"),
diff --git a/R/UCSC.api.url.R b/R/UCSC.api.url.R
index 9d47b87..b8d3394 100644
--- a/R/UCSC.api.url.R
+++ b/R/UCSC.api.url.R
@@ -4,16 +4,16 @@
 ###
 
 
-UCSC.api.url <- function(new_url=NULL)
+UCSC.api.url <- function(url=NULL)
 {
     ans <- getOption("UCSC.api.url")
-    if (is.null(new_url))
+    if (is.null(url))
         return(ans)
-    if (!(isSingleString(new_url) && nzchar(new_url)))
-        stop(wmsg("'new_url' must be a single (non-empty) string"))
-    if (!startsWith(tolower(new_url), "http"))
-        stop(wmsg("'new_url' must start with \"http\""))
-    options(UCSC.api.url=new_url)
+    if (!(isSingleString(url) && nzchar(url)))
+        stop(wmsg("'url' must be a single (non-empty) string"))
+    if (!startsWith(tolower(url), "http"))
+        stop(wmsg("'url' must start with \"http\""))
+    options(UCSC.api.url=url)
     invisible(ans)  # return old URL invisibly
 }
 
diff --git a/man/UCSC.api.url.Rd b/man/UCSC.api.url.Rd
index 95b27c3..5c7427b 100644
--- a/man/UCSC.api.url.Rd
+++ b/man/UCSC.api.url.Rd
@@ -5,36 +5,41 @@
 \title{Get or set the default UCSC API URL}
 
 \description{
-  Get or set the default UCSC API URL.
+  Convenience helper for getting or setting global option \code{UCSC.api.url}.
 }
 
 \usage{
-UCSC.api.url(new_url=NULL)
+UCSC.api.url(url=NULL)
 }
 
 \arguments{
-  \item{new_url}{
+  \item{url}{
     Alternative UCSC API URL to use by default.
   }
 }
 
 \details{
-  \code{UCSC.api.url()} is just a convenience wrapper for
-  \code{getOption("UCSC.api.url")}.
+  Various functions in the \pkg{UCSC.utils} package query the UCSC REST API.
+  This is the case for example for \code{\link{list_UCSC_genomes}},
+  \code{\link{get_UCSC_chrom_sizes}}, \code{\link{list_UCSC_tracks}}
+  and others.
+
+  Global option \code{UCSC.api.url} controls the UCSC API URL
+  that these functions use y default. The option is set to
+  \code{"https://api.genome.ucsc.edu"} at package startup.
 
-  To change the default UCSC API URL, call \code{UCSC.api.url(new_url)}
-  where \code{new_url} is a single string containing the alternative URL.
-  Note that this is just a convenience wrapper for
-  \code{options(UCSC.api.url=new_url)}.
+  \code{UCSC.api.url()} and \code{UCSC.api.url(url)} are provided
+  as convenient ways of doing \code{getOption("UCSC.api.url")}
+  and \code{options(UCSC.api.url=url)}, respectively.
 }
 
 \value{
-  When called with no argument, \code{UCSC.api.url()} returns the URL of
-  the UCSC API that is currently used by default.
+  When called with no argument, \code{UCSC.api.url()} returns
+  \code{getOption("UCSC.api.url")}.
 
-  When passed a new URL, \code{UCSC.api.url(new_url)} returns the URL of
-  the UCSC API that was \emph{previously} used by default. Note that the
-  URL is returned invisibly.
+  When passed an URL, \code{UCSC.api.url(url)} returns the \emph{old} URL,
+  that is, the UCSC API URL that was previously used by default. Note
+  that the \emph{old} URL is returned invisibly.
 }
 
 \seealso{
@@ -47,14 +52,16 @@ UCSC.api.url(new_url=NULL)
 }
 
 \examples{
-UCSC.api.url()  # current default UCSC API URL
+UCSC.api.url()  # current default value of the UCSC API URL
 get_UCSC_chrom_sizes("ce11", recache=TRUE)
 
 ## Temporarily use the mirror in Asia:
 old_url <- UCSC.api.url("https://genome-asia.ucsc.edu/cgi-bin/hubApi")
+UCSC.api.url()  # new default value of the UCSC API URL
+\donttest{
 get_UCSC_chrom_sizes("ce11", recache=TRUE)
-
-## Restore old URL:
+}
+## Restore old default value:
 UCSC.api.url(old_url)
 }
 
diff --git a/vignettes/UCSC.utils.Rmd b/vignettes/UCSC.utils.Rmd
index bb1344b..5bcdb62 100644
--- a/vignettes/UCSC.utils.Rmd
+++ b/vignettes/UCSC.utils.Rmd
@@ -1,9 +1,9 @@
 ---
-title: "The **UCSC.utils** package"
+title: "The _UCSC.utils_ package"
 author:
 - name: Hervé Pagès
   affiliation: Fred Hutchinson Cancer Research Center, Seattle, WA
-date: "Compiled `r doc_date()`; Modified 8 April 2024"
+date: "Compiled `r doc_date()`; Modified 16 April 2024"
 package: UCSC.utils
 vignette: |
   %\VignetteIndexEntry{The UCSC.utils package}