diff --git a/CRAN-RELEASE b/CRAN-RELEASE
new file mode 100644
index 0000000..daac877
--- /dev/null
+++ b/CRAN-RELEASE
@@ -0,0 +1,2 @@
+This package was submitted to CRAN on 2021-04-23.
+Once it is accepted, delete this file and tag the release (commit a33f9681e7a9a).
diff --git a/NEWS.md b/NEWS.md
index 3042e47..7af7aa2 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -3,7 +3,7 @@
 [latest news on GitHub](https://github.com/NYPL/libbib/blob/master/NEWS.md)
 where the formatting is better.**
 
-# libbib 2.0 (in development)
+# libbib 1.5
 
 ## new features
 
diff --git a/R/worldcat-api.R b/R/worldcat-api.R
index 47ce8d0..024540f 100755
--- a/R/worldcat-api.R
+++ b/R/worldcat-api.R
@@ -329,8 +329,8 @@ worldcat_api_bib_read_info_by_something <- function(x,
 #'          chosen accepts.
 #' @param wskey A WorldCat API key (default is \code{getOption("libbib.wskey")})
 #' @param more A logical indicating whether more infomation from the MARCXML
-#'             should be returned (publisher, etc....) In the interest of
-#'             memory consumption, the default is \code{FALSE}
+#'             should be returned (publisher, bib level etc....) In the
+#'             interest of memory consumption, the default is \code{FALSE}
 #' @param debug A logical indicating whether the HTTP and bib read API
 #'              responses should be printed (for debugging)
 #'              (default is \code{FALSE})
@@ -720,11 +720,12 @@ worldcat_api_locations_by_something <- function(x,
 #'                     an application where a user is not logged in to an
 #'                     institution, set this to "default". It is up to you
 #'                     to respect the WorldCat API's conditions.
-#' @param frbrGrouping With this parameter set to "on" (default), an attempt
-#'                     is made by the WorldCat API to group equivalent works
-#'                     (different editions, format, etc...) together. If not,
-#'                     only institutions holding the exact standard number
-#'                     specified will be returned.
+#' @param frbrGrouping With this parameter set to "on" (default),
+#'                     an attempt is made by the WorldCat API to group
+#'                     together similar editions and present only the top
+#'                     held record as the representative record for that group.
+#'                     If not, only institutions holding the exact standard
+#'                     number specified will be returned.
 #' @param libtype One of \code{NULL} (default), "academic", "public",
 #'                "government", or "other". \code{NULL} will return all
 #'                library subsets. The others will only search for holdings
@@ -864,7 +865,6 @@ worldcat_api_locations_by_issn <- function(x,
 construct_wcapi_search_url <- function(sru, max_records=100,
                                        frbrGrouping="on", start_at=1,
                                        wskey=getOption("libbib.wskey", "")){
-
   # error checking
   if(class(sru)!="character")
     stop("SRU search must be a string")
@@ -952,26 +952,81 @@ worldcat_api_search_helper <- function(sru, max_records=100,
 
 #' Use the WorldCat Search API
 #'
-#' STUB
+#' Searches WorldCat using a CQL query. Returns a \code{data.table}
+#' containing the bibliographic metadata of the results, along
+#' with the total number of results.
 #'
-#' @param sru STUB
-#' @param max_records STUB
-#' @param frbrGrouping STUB
-#' @param start_at STUB
-#' @param wskey STUB
-#' @param more STUB
-#' @param print.progress STUB
-#' @param debug STUB
+#' @param sru The search query (in CQL syntax). See \code{examples} section
+#'            for some examples.
+#' @param max_records The maximum number of search results to return.
+#'                    Must be a number between 0 and 100 or \code{Inf}.
+#'                    If \code{Inf} (default), the function will
+#'                    automatically make all follow-up requests to retrieve
+#'                    all search results. For safety, the default is 10.
+#' @param frbrGrouping With this parameter set to "on" (default),
+#'                     an attempt is made by the WorldCat API to group
+#'                     together similar editions and present only the top
+#'                     held record as the representative record for that group.
+#' @param start_at The search result to start at (default is 1)
+#' @param wskey A WorldCat API key (default is \code{getOption("libbib.wskey")})
+#' @param more A logical indicating whether more infomation from the MARCXML
+#'             search results should be returned (publisher, bib level, etc....).
+#'             (Default is \code{TRUE})
+#' @param print.progress A logical indicating whether a message should be
+#'                       displayed for each API request. If \code{max_records}
+#'                       is \code{TRUE} a message will be displayed for every
+#'                       group of 100 search results the function fetches.
+#'                       (default is \code{TRUE})
+#' @param debug A logical indicating whether the HTTP and API
+#'              responses should be printed (for debugging)
+#'              (default is \code{FALSE})
 #'
 #' @details
-#' STUB
 #'
-#' @return STUB
+#' As with all API access functions in this package, it's up to the
+#' user to limit their API usage so as to not get blocked. These
+#' functions are deliberately not vectorized for this reason; they
+#' only accept one standard number at a time.
+#'
+#' This (and other) WorldCat API communication functions require a
+#' WorldCat API key. The easiest way to use these functions is to
+#' set a global options with your key:
+#' \code{options("libbib.wskey"="YOUR KEY HERE")}
+#'
+#' @return A \code{data.table} containing the bibliographic metadata of the
+#'         results, along with the total number of results.
 #'
 #' @examples
 #'
-#' # STUB
+#' \dontrun{
+#'
+#' # A title search of "The Brothers Karamazov"
+#' worldcat_api_search('srw.ti="Brothers Karamazov"')
 #'
+#' # Search for title "Madame Bovary" by author "Gustave Flaubert"
+#' # in language Greek (all results)
+#' sru <- 'srw.au="Gustave Flaubert" and srw.ti="Madame Bovary" and srw.la=gre'
+#' worldcat_api_search(sru, max_records=Inf)
+#'
+#' # Hip Hop (subject) materials on Cassette, CD, or wax from years 1987 to 1990
+#' sru <- '((srw.mt=cas or srw.mt=cda or srw.mt=lps) and srw.su="Rap") and srw.yr="1987-1990"'
+#' worldcat_api_search(sru)
+#'
+#' # all materials with keyword "Common Lisp" at The New York Public Library
+#' sru <- 'srw.kw="common lisp" and srw.li=NYP'
+#' worldcat_api_search(sru, max_records=Inf)
+#'
+#' # 19th century materials on ethics (Dewey code 170s / LC Call prefix BJ)
+#' sru <- '(srw.dd="17*" or srw.lc="bj*") and srw.yr="18*"'
+#' worldcat_api_search(sru, max_records=Inf)
+#'
+#' # Music (Dewey 780s) materials that are only held by The New York Public
+#' # Library (a "cg" code of 11 means there is only one holding)
+#' # [searching with debugging]
+#' sru <- 'srw.dd="78*" and srw.li=NYP and srw.cg=11'
+#' worldcat_api_search(sru, debug=TRUE)
+#'
+#' }
 #' @export
 worldcat_api_search <- function(sru, max_records=10,
                                  frbrGrouping="on", start_at=1,
diff --git a/README.md b/README.md
index 6ed9b02..fe8521d 100755
--- a/README.md
+++ b/README.md
@@ -8,11 +8,12 @@ libbib <img src="http://statethatiamin.com/media/libbibsmall.png" align="right"
 
 
 ## Description
-An R package providing functions for for validating and normalizing
-bibliographic codes such as ISBN, ISSN, and LCCN. Includes functions to
-translate Call numbers (Library of Congress and Dewey Decimal) to their
-subject classifications or subclassifications. Also provides various
-loadable data files such call number / subject crosswalks and code
+An R package providing WorldCat API communication, functions for validating
+and normalizing bibliographic codes such as ISBN; ISSN; and LCCN, translation
+from call numbers (Library of Congress and Dewey Decimal) to their subject
+classifications or subclassifications, and other related utilities helpful
+for assessment librarians. Also provides various loadable data files such
+call number / subject crosswalks and code tables.
 
 Speed of execution and robustness are priorities in this package.
 To the end of optimizing speed and efficiency, careful consideration
@@ -53,6 +54,18 @@ automated tests, at time of writing
 > normalize_lccn(" 79139101 /AC/r932")
 [1] "79139101"
 
+> # Do a WorldCat APU search on 19th century materials on ethics
+> # (Dewey code 170s / LC Call prefix BJ)
+> results <- worldcat_api_search('(srw.dd="17*" or srw.lc="bj*") and srw.yr="18*"')
+> results[,.(oclc, title, result_number, num_results)][1:5]
+        oclc                                       title result_number num_results
+      <char>                                      <char>         <int>      <char>
+1:   8665856 The principles of moral and political ph...             1        1716
+2: 191264919                The economy of human life. /             2        1716
+3:  22571399                                   Solitude:             3        1716
+4:  65250134 The theory of moral sentiments, or, An e...             4        1716
+5:  13106952    Letters on the improvement of the mind :             5        1716 
+
 > worldcat_api_bib_read_info_by_isbn("9780984201006")
         oclc          isbn   issn                        title
       <char>        <char> <char>                       <char>
diff --git a/cran-comments.md b/cran-comments.md
index 807c405..e68f830 100644
--- a/cran-comments.md
+++ b/cran-comments.md
@@ -8,5 +8,7 @@
 
 When checked with --as-cran and --no-manual
 there were no ERRORs or WARNINGs but 1 NOTE related
-to being a new submission
+to "WorldCat" being a possibly mis-spelled word
+(but it's a valid term in the context of this
+package)
 
diff --git a/data/books_serials_etc_sample.rda b/data/books_serials_etc_sample.rda
index 983b368..005a7fe 100644
Binary files a/data/books_serials_etc_sample.rda and b/data/books_serials_etc_sample.rda differ
diff --git a/man/worldcat_api_bib_read_info_by.Rd b/man/worldcat_api_bib_read_info_by.Rd
index 64375c3..0a27b75 100644
--- a/man/worldcat_api_bib_read_info_by.Rd
+++ b/man/worldcat_api_bib_read_info_by.Rd
@@ -35,8 +35,8 @@ chosen accepts.}
 \item{wskey}{A WorldCat API key (default is \code{getOption("libbib.wskey")})}
 
 \item{more}{A logical indicating whether more infomation from the MARCXML
-should be returned (publisher, etc....) In the interest of
-memory consumption, the default is \code{FALSE}}
+should be returned (publisher, bib level etc....) In the
+interest of memory consumption, the default is \code{FALSE}}
 
 \item{debug}{A logical indicating whether the HTTP and bib read API
 responses should be printed (for debugging)
diff --git a/man/worldcat_api_locations_by.Rd b/man/worldcat_api_locations_by.Rd
index 795a9a5..e9cf5d9 100644
--- a/man/worldcat_api_locations_by.Rd
+++ b/man/worldcat_api_locations_by.Rd
@@ -85,11 +85,12 @@ an application where a user is not logged in to an
 institution, set this to "default". It is up to you
 to respect the WorldCat API's conditions.}
 
-\item{frbrGrouping}{With this parameter set to "on" (default), an attempt
-is made by the WorldCat API to group equivalent works
-(different editions, format, etc...) together. If not,
-only institutions holding the exact standard number
-specified will be returned.}
+\item{frbrGrouping}{With this parameter set to "on" (default),
+an attempt is made by the WorldCat API to group
+together similar editions and present only the top
+held record as the representative record for that group.
+If not, only institutions holding the exact standard
+number specified will be returned.}
 
 \item{libtype}{One of \code{NULL} (default), "academic", "public",
 "government", or "other". \code{NULL} will return all
diff --git a/man/worldcat_api_search.Rd b/man/worldcat_api_search.Rd
index ce69a6b..5ce2f29 100644
--- a/man/worldcat_api_search.Rd
+++ b/man/worldcat_api_search.Rd
@@ -16,33 +16,87 @@ worldcat_api_search(
 )
 }
 \arguments{
-\item{sru}{STUB}
+\item{sru}{The search query (in CQL syntax). See \code{examples} section
+for some examples.}
 
-\item{max_records}{STUB}
+\item{max_records}{The maximum number of search results to return.
+Must be a number between 0 and 100 or \code{Inf}.
+If \code{Inf} (default), the function will
+automatically make all follow-up requests to retrieve
+all search results. For safety, the default is 10.}
 
-\item{frbrGrouping}{STUB}
+\item{frbrGrouping}{With this parameter set to "on" (default),
+an attempt is made by the WorldCat API to group
+together similar editions and present only the top
+held record as the representative record for that group.}
 
-\item{start_at}{STUB}
+\item{start_at}{The search result to start at (default is 1)}
 
-\item{wskey}{STUB}
+\item{wskey}{A WorldCat API key (default is \code{getOption("libbib.wskey")})}
 
-\item{more}{STUB}
+\item{more}{A logical indicating whether more infomation from the MARCXML
+search results should be returned (publisher, bib level, etc....).
+(Default is \code{TRUE})}
 
-\item{print.progress}{STUB}
+\item{print.progress}{A logical indicating whether a message should be
+displayed for each API request. If \code{max_records}
+is \code{TRUE} a message will be displayed for every
+group of 100 search results the function fetches.
+(default is \code{TRUE})}
 
-\item{debug}{STUB}
+\item{debug}{A logical indicating whether the HTTP and API
+responses should be printed (for debugging)
+(default is \code{FALSE})}
 }
 \value{
-STUB
+A \code{data.table} containing the bibliographic metadata of the
+        results, along with the total number of results.
 }
 \description{
-STUB
+Searches WorldCat using a CQL query. Returns a \code{data.table}
+containing the bibliographic metadata of the results, along
+with the total number of results.
 }
 \details{
-STUB
+As with all API access functions in this package, it's up to the
+user to limit their API usage so as to not get blocked. These
+functions are deliberately not vectorized for this reason; they
+only accept one standard number at a time.
+
+This (and other) WorldCat API communication functions require a
+WorldCat API key. The easiest way to use these functions is to
+set a global options with your key:
+\code{options("libbib.wskey"="YOUR KEY HERE")}
 }
 \examples{
 
-# STUB
+\dontrun{
+
+# A title search of "The Brothers Karamazov"
+worldcat_api_search('srw.ti="Brothers Karamazov"')
+
+# Search for title "Madame Bovary" by author "Gustave Flaubert"
+# in language Greek (all results)
+sru <- 'srw.au="Gustave Flaubert" and srw.ti="Madame Bovary" and srw.la=gre'
+worldcat_api_search(sru, max_records=Inf)
+
+# Hip Hop (subject) materials on Cassette, CD, or wax from years 1987 to 1990
+sru <- '((srw.mt=cas or srw.mt=cda or srw.mt=lps) and srw.su="Rap") and srw.yr="1987-1990"'
+worldcat_api_search(sru)
 
+# all materials with keyword "Common Lisp" at The New York Public Library
+sru <- 'srw.kw="common lisp" and srw.li=NYP'
+worldcat_api_search(sru, max_records=Inf)
+
+# 19th century materials on ethics (Dewey code 170s / LC Call prefix BJ)
+sru <- '(srw.dd="17*" or srw.lc="bj*") and srw.yr="18*"'
+worldcat_api_search(sru, max_records=Inf)
+
+# Music (Dewey 780s) materials that are only held by The New York Public
+# Library (a "cg" code of 11 means there is only one holding)
+# [searching with debugging]
+sru <- 'srw.dd="78*" and srw.li=NYP and srw.cg=11'
+worldcat_api_search(sru, debug=TRUE)
+
+}
 }