diff --git a/NAMESPACE b/NAMESPACE
index 36a466c..22f12d6 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -1,9 +1,11 @@
 # Generated by roxygen2: do not edit by hand
 
 export(cosine_sim)
+export(dataset_names)
 export(id2char)
 export(partner_summary2adjacency_matrix)
 export(prepare_cosine_matrix)
+export(register_dataset)
 importFrom(grDevices,hcl.colors)
 importFrom(stats,as.dist)
 importFrom(stats,hclust)
diff --git a/R/datasets.R b/R/datasets.R
index 0ac870b..dfc334c 100644
--- a/R/datasets.R
+++ b/R/datasets.R
@@ -19,10 +19,14 @@
 #'   only used for testing purposes.
 #' @param ... Additional named arguments specifying properties of the dataset
 #'
-#' @return
+#' @return No return value. Called for its side effect.
 #' @export
 #'
 #' @examples
+#' \dontrun{
+#' # partial example. metafun and partnerfun are pretty important to specify
+#' register_dataset("flywire", shortname='fw', species='Drosophila melanogaster', sex='F', age="adult")
+#' }
 register_dataset <- function(name, shortname=NULL, species=NULL,
                              sex=c("F", "M", "H", "U"), age=NULL,
                              idfun=NULL, metafun=NULL, partnerfun=NULL,
@@ -74,13 +78,17 @@ dataset_namespace <- function(namespace='default') {
 #' Return dataset names either all or those matching a query
 #'
 #' @param query A character vector partially matched against dataset names
-#' @param short Whether to match (and return) short names
-#' @param namespace
+#' @param namespace Optional character vector specifying a namespace used to
+#'   organise datasets (advanced use only).
+#' @param return.short Whether to return the long or short name
+#' @param match Whether the query should match against long or short forms of
+#'   the dataset name.
 #'
-#' @return
+#' @return A character vector of names
 #' @export
 #'
 #' @examples
+#' dataset_names()
 dataset_names <- function(query=NULL, return.short=FALSE, match=c("both", "long", "short"), namespace='default') {
 
   ns=dataset_namespace(namespace)
diff --git a/man/dataset_names.Rd b/man/dataset_names.Rd
new file mode 100644
index 0000000..9785186
--- /dev/null
+++ b/man/dataset_names.Rd
@@ -0,0 +1,33 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/datasets.R
+\name{dataset_names}
+\alias{dataset_names}
+\title{Return dataset names either all or those matching a query}
+\usage{
+dataset_names(
+  query = NULL,
+  return.short = FALSE,
+  match = c("both", "long", "short"),
+  namespace = "default"
+)
+}
+\arguments{
+\item{query}{A character vector partially matched against dataset names}
+
+\item{return.short}{Whether to return the long or short name}
+
+\item{match}{Whether the query should match against long or short forms of
+the dataset name.}
+
+\item{namespace}{Optional character vector specifying a namespace used to
+organise datasets (advanced use only).}
+}
+\value{
+A character vector of names
+}
+\description{
+Return dataset names either all or those matching a query
+}
+\examples{
+dataset_names()
+}
diff --git a/man/register_dataset.Rd b/man/register_dataset.Rd
new file mode 100644
index 0000000..b6b48d1
--- /dev/null
+++ b/man/register_dataset.Rd
@@ -0,0 +1,58 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/datasets.R
+\name{register_dataset}
+\alias{register_dataset}
+\title{Register a dataset for use with coconat and related packages}
+\usage{
+register_dataset(
+  name,
+  shortname = NULL,
+  species = NULL,
+  sex = c("F", "M", "H", "U"),
+  age = NULL,
+  idfun = NULL,
+  metafun = NULL,
+  partnerfun = NULL,
+  namespace = "default",
+  ...
+)
+}
+\arguments{
+\item{name}{The long name of the dataset; this must be unique}
+
+\item{shortname}{An abbreviation for the dataset - will be used to construct
+keys and plot labels etc}
+
+\item{species}{The binomial name for the species}
+
+\item{sex}{Female, Male, Hermaphrodite or Uncertain}
+
+\item{age}{A description of the stage (e.g. adult or L1 or P19)}
+
+\item{idfun}{A function or function name to fetch ids based on a query
+specification.}
+
+\item{metafun}{A function or function name to fetch metadata about a set of
+ids for this dataset.}
+
+\item{partnerfun}{A function or function name to fetch connections for ids in
+this dataset.}
+
+\item{namespace}{Expert use only. Can be used to define separate namespaces
+across which dataset names and keys do not have to be unique. Currently
+only used for testing purposes.}
+
+\item{...}{Additional named arguments specifying properties of the dataset}
+}
+\value{
+No return value. Called for its side effect.
+}
+\description{
+Register a dataset for use with coconat and related packages
+}
+\examples{
+\dontrun{
+# partial example. metafun and partnerfun are pretty important to specify
+register_dataset("flywire", shortname='fw', species='Drosophila melanogaster', sex='F', age="adult")
+}
+}