update version and documentation

8 files changed, 134 insertions, 25 deletions

diff --git a/DESCRIPTION b/DESCRIPTION
index be7806f..12c5191 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -1,6 +1,6 @@
 Package: SyncRNG
-Version: 1.2.1
-Date: 2016-10-16
+Version: 1.3.0
+Date: 2017-12-15
 Title: A Synchronized Tausworthe RNG for R and Python
 Author: Gertjan van den Burg <gertjanvandenburg@gmail.com>
 Maintainer: Gertjan van den Burg <gertjanvandenburg@gmail.com>
diff --git a/NAMESPACE b/NAMESPACE
index 160a4f2..052e9e8 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -2,5 +2,6 @@
 
 export(SyncRNG)
 exportClasses(SyncRNG)
+import(methods)
 importFrom(methods,new)
-useDynLib(SyncRNG)
+useDynLib(SyncRNG, .registration = TRUE)
diff --git a/R/SyncRNG.R b/R/SyncRNG.R
index 95e6b3e..e7176b4 100644
--- a/R/SyncRNG.R
+++ b/R/SyncRNG.R
@@ -1,12 +1,14 @@
 library(methods)
 
 #' A Reference Class for SyncRNG
+#' 
+#' See \link{syncrng-package} for package documentation.
 #'
 #' @field seed The seed for the random number generator
 #' @field state The current state of the RNG, should not be modified by the 
 #' user
 #'
-#' @useDynLib SyncRNG
+#' @useDynLib SyncRNG, .registration = TRUE
 #' @export SyncRNG
 #' @exportClass SyncRNG
 #' @importFrom methods new
diff --git a/R/syncrng-package.R b/R/syncrng-package.R
new file mode 100644
index 0000000..949401d
--- /dev/null
+++ b/R/syncrng-package.R
@@ -0,0 +1,50 @@
+#' @title SyncRNG - Synchronized Random Numbers in R and Python
+#' 
+#' @description 
+#' The SyncRNG package provides a random number generator implemented in C and 
+#' linked to both R and Python. This way, you can generate the same random 
+#' number sequence in both languages by using the same seed.
+#'
+#' The package implements a Tausworthe LSFR RNG (more details at 
+#' \url{https://gertjanvandenburg.com/blog/syncrng/}). This is a very fast 
+#' pseudo-random number generator.
+#'
+#' @section Usage:
+#' There are two ways to use this package in R. It can be used as a reference 
+#' class, where a SyncRNG object is used to keep the state of the generator and 
+#' numbers are generated using the object methods. It can also be used as a 
+#' user-defined random number generator using the strategy outlined in 
+#' .Random.user. See the examples section below.
+#'
+#' @author
+#' Gerrit J.J. van den Burg\cr
+#' Maintainer: Gerrit J.J. van den Burg <gertjanvandenburg@gmail.com>
+#'
+#' @references
+#' URL: \url{https://github.com/GjjvdBurg/SyncRNG}
+#'
+#' @examples
+#' library(SyncRNG)
+#'
+#' # As user defined RNG:
+#'
+#' set.seed(0, 'user', 'user')
+#' runif(2)
+#' # [1] 3.666952e-04 6.257184e-05
+#' set.seed(0, 'user', 'user')
+#' rnorm(2)
+#' # [1] 0.01006027 0.42889422
+#'
+#' # As class:
+#'
+#' s <- SyncRNG(seed=0)
+#' s$rand()
+#' # [1] 0.0003666952
+#' s$rand()
+#' # [1] 6.257184e-05
+#'
+#' @name syncrng-package
+#' @docType package
+#' @import methods
+NULL
+#>NULL
diff --git a/README.md b/README.md
index 08afc28..d7aa3bc 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,3 @@
-=======
 SyncRNG
 =======
 A synchronized Tausworthe RNG usable in R and Python.
@@ -6,15 +5,18 @@ A synchronized Tausworthe RNG usable in R and Python.
 Why?
 ====
 
-This program was created because it was desired to have the same random 
-numbers in both R and Python programs. Although both languages implement a 
-Mersenne-Twister RNG, the implementations are so different that it is not 
-possible to get the same random numbers with the same seed.
+This program was created because I needed to have the same random numbers in 
+both R and Python. Although both languages implement a Mersenne-Twister RNG, 
+the implementations are so different that it is not possible to get the same 
+random numbers with the same seed.
 
 SyncRNG is a Tausworthe RNG implemented in ``syncrng.c``, and linked to both R 
 and Python. Since both use the same underlying C code, the random numbers will 
 be the same in both languages, provided the same seed is used.
 
+You can read more about my motivations for creating this 
+[here](https://gertjanvandenburg.com/blog/syncrng/).
+
 How
 ===
 
@@ -38,6 +40,21 @@ Similarly, after installing the R library you can do in R::
 
 You'll notice that the random numbers are indeed the same.
 
+R - User defined RNG
+--------------------
+
+R allows the user to define a custom random number generator, which is then 
+used for the common ``runif`` and ``rnorm`` functions in R. This has also been 
+implemented in SyncRNG as of version 1.3.0. To enable this, run::
+
+    library(SyncRNG)
+
+    set.seed(123456, 'user', 'user')
+    runif(10)
+
+These numbers are between [0, 1) and multiplying by ``2**32 - 1`` gives the 
+same results as above.
+
 Installation
 ============
 
diff --git a/cran-comments.md b/cran-comments.md
index c75610f..168c814 100644
--- a/cran-comments.md
+++ b/cran-comments.md
@@ -1,19 +1,6 @@
-## Resubmission
-This is a resubmission. In this version I have:
-* removed the LICENSE file
-* updated the DESCRIPTION to state "License: GPL-2"
-
 ## Test environments
-* local Arch Linux install, R 3.3.1
+* local Arch Linux install, R 3.4.3
 * win-builder (devel and release)
 
 ## R CMD check results
-There were no ERRORs or WARNINGs.
-
-There was 1 NOTE:
-
-* checking CRAN incoming feasibility ... NOTE
-  Maintainer: ‘Gertjan van den Burg <gertjanvandenburg@gmail.com>’
-
-  New submission
-
+There were no ERRORs or WARNINGs or NOTEs.
diff --git a/man/SyncRNG-class.Rd b/man/SyncRNG-class.Rd
index 6f6d27d..7a2c69b 100644
--- a/man/SyncRNG-class.Rd
+++ b/man/SyncRNG-class.Rd
@@ -6,7 +6,7 @@
 \alias{SyncRNG-class}
 \title{A Reference Class for SyncRNG}
 \description{
-A Reference Class for SyncRNG
+See \link{syncrng-package} for package documentation.
 }
 \section{Fields}{
 
diff --git a/man/syncrng-package.Rd b/man/syncrng-package.Rd
new file mode 100644
index 0000000..a1b3d32
--- /dev/null
+++ b/man/syncrng-package.Rd
@@ -0,0 +1,52 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/syncrng-package.R
+\docType{package}
+\name{syncrng-package}
+\alias{syncrng-package}
+\title{SyncRNG - Synchronized Random Numbers in R and Python}
+\description{
+The SyncRNG package provides a random number generator implemented in C and 
+linked to both R and Python. This way, you can generate the same random 
+number sequence in both languages by using the same seed.
+
+The package implements a Tausworthe LSFR RNG (more details at 
+\url{https://gertjanvandenburg.com/blog/syncrng/}). This is a very fast 
+pseudo-random number generator.
+}
+\section{Usage}{
+
+There are two ways to use this package in R. It can be used as a reference 
+class, where a SyncRNG object is used to keep the state of the generator and 
+numbers are generated using the object methods. It can also be used as a 
+user-defined random number generator using the strategy outlined in 
+.Random.user. See the examples section below.
+}
+\examples{
+library(SyncRNG)
+
+# As user defined RNG:
+
+set.seed(0, 'user', 'user')
+runif(2)
+# [1] 3.666952e-04 6.257184e-05
+set.seed(0, 'user', 'user')
+rnorm(2)
+# [1] 0.01006027 0.42889422
+
+# As class:
+
+s <- SyncRNG(seed=0)
+s$rand()
+# [1] 0.0003666952
+s$rand()
+# [1] 6.257184e-05
+
+}
+\author{
+Gerrit J.J. van den Burg\cr
+Maintainer: Gerrit J.J. van den Burg <gertjanvandenburg@gmail.com>
+}
+\references{
+URL: \url{https://github.com/GjjvdBurg/SyncRNG}
+}
+