diff --git a/R/bitset.R b/R/bitset.R
index 8a2d623..1e11f57 100644
--- a/R/bitset.R
+++ b/R/bitset.R
@@ -1,3 +1,38 @@
+#' Generate documentation for an R6-like method
+#'
+#' The Bitset class is implemented as a named list with closures that capture
+#' the environment. By default, roxygen2 generates terrible documentation for
+#' it since it isn't a typical way of doing things.
+#'
+#' This method generates a snippet of Rd code for a method, in a way that
+#' resembles the code roxygen2 generates for R6 methods.
+#'
+#' @noRd
+bitset_method_doc <- function(name, description, ...) {
+ arguments <- list(...)
+ lines <- character()
+ push <- function(...) lines <<- c(lines, ...)
+
+ push("\\if{html}{\\out{
}}")
+ push(paste0("\\subsection{Method \\code{", name, "()}}{"))
+ push(description)
+ push("\\subsection{Usage}{")
+ argnames <- paste(names(arguments), collapse=", ")
+ push(paste0("\\preformatted{Bitset$", name, "(", argnames, ")}"))
+ push("}")
+ if (length(arguments) > 0) {
+ push("\\subsection{Arguments}{")
+ push("\\describe{")
+ push(sprintf("\\item{\\code{%s}}{%s}", names(arguments), arguments))
+ push("}")
+ push("}")
+ }
+ push("}")
+
+ paste(lines, collapse="\n")
+ # lines
+}
+
#' @title A Bitset Class
#' @description This is a data structure that compactly stores the presence of
#' integers in some finite set (\code{max_size}), and can
@@ -8,13 +43,14 @@
#'
#' This class is defined as a named list for performance reasons, but for most
#' intents and purposes it behaves just like an R6 class.
-#'
+#' @format NULL
+#' @usage NULL
+#' @docType NULL
+#' @keywords NULL
#' @export
+#' @section Methods:
Bitset <- list(
- #' @description create a bitset.
- #' @param size the size of the bitset.
- #' @param from pointer to an existing IterableBitset to use; if \code{NULL}
- #' make empty bitset, otherwise copy existing bitset.
+ #' `r bitset_method_doc("new", "create a bitset.", size = "the size of the bitset.", from="pointer to an existing IterableBitset to use; if \\code{NULL} make empty bitset, otherwise copy existing bitset.")`
new = function(size, from = NULL) {
if (is.null(from)) {
bitset <- create_bitset(size)
@@ -28,69 +64,57 @@ Bitset <- list(
.bitset = bitset,
max_size = max_size,
- #' @description insert into the bitset.
- #' @param v an integer vector of elements to insert.
+ #' `r bitset_method_doc("insert", "insert into the bitset.", v = "an integer vector of elements to insert.")`
insert = function(v) {
bitset_insert(self$.bitset, v)
self
},
- #' @description remove from the bitset.
- #' @param v an integer vector of elements (not indices) to remove.
+ #' `r bitset_method_doc("remove", "insert from the bitset.", v = "an integer vector of elements (not indices) to remove.")`
remove = function(v) {
bitset_remove(self$.bitset, v)
self
},
- #' @description clear the bitset.
+ #' `r bitset_method_doc("clear", "clear the bitset.")`
clear = function() {
bitset_clear(self$.bitset)
self
},
- #' @description get the number of elements in the set.
+ #' `r bitset_method_doc("size", "get the number of elements in the set.")`
size = function() bitset_size(self$.bitset),
- #' @description to "bitwise or" or union two bitsets.
- #' @param other the other bitset.
+ #' `r bitset_method_doc("or", "to \"bitwise or\" or union two bitsets.", other = "the other bitset.")`
or = function(other) {
bitset_or(self$.bitset, other$.bitset)
self
},
- #' @description to "bitwise and" or intersect two bitsets.
- #' @param other the other bitset.
+ #' `r bitset_method_doc("and", "to \"bitwise and\" or intersect two bitsets.", other = "the other bitset.")`
and = function(other) {
bitset_and(self$.bitset, other$.bitset)
self
},
- #' @description to "bitwise not" or complement a bitset.
- #' @param inplace whether to overwrite the current bitset, default = TRUE
+ #' `r bitset_method_doc("not", "to \"bitwise not\" or complement a bitset.", inplace = "whether to overwrite the current bitset, default = TRUE")`
not = function(inplace = TRUE) {
Bitset$new(from = bitset_not(self$.bitset, inplace))
},
- #' @description to "bitwise xor" or get the symmetric difference of two bitset
- #' (keep elements in either bitset but not in their intersection).
- #' @param other the other bitset.
+ #' `r bitset_method_doc("xor", "to \"bitwise xor\" get the symmetric difference of two bitset (keep elements in either bitset but not in their intersection).", other = "the other bitset.")`
xor = function(other){
bitset_xor(self$.bitset, other$.bitset)
self
},
- #' @description Take the set difference of this bitset with another
- #' (keep elements of this bitset which are not in \code{other}).
- #' @param other the other bitset.
+ #' `r bitset_method_doc("set_difference", "Take the set difference of this bitset with another (keep elements of this bitset which are not in \\code{other})", other = "the other bitset.")`
set_difference = function(other){
bitset_set_difference(self$.bitset, other$.bitset)
self
},
- #' @description sample a bitset.
- #' @param rate the success probability for keeping each element, can be
- #' a single value for all elements or a vector of unique
- #' probabilities for keeping each element.
+ #' `r bitset_method_doc("sample", "sample a bitset.", rate = "the success probability for keeping each element, can be a single value for all elements or a vector of unique probabilities for keeping each element.")`
sample = function(rate) {
stopifnot(is.finite(rate), !is.null(rate))
if (length(rate) == 1) {
@@ -101,10 +125,7 @@ Bitset <- list(
self
},
- #' @description choose k random items in the bitset
- #' @param k the number of items in the bitset to keep. The selection of
- #' these k items from N total items in the bitset is random, and
- #' k should be chosen such that \eqn{0 \le k \le N}.
+ #' `r bitset_method_doc("choose", "choose k random items in the bitset.", k = "the number of items in the bitset to keep. The selection of these k items from N total items in the bitset is random, and k should be chosen such that \\eqn{0 \\le k \\le N}.")`
choose = function(k) {
stopifnot(is.finite(k))
stopifnot(k <= bitset_size(self$.bitset))
@@ -115,13 +136,13 @@ Bitset <- list(
self
},
- #' @description returns a copy the bitset.
+ #' `r bitset_method_doc("copy", "returns a copy of the bitset.")`
copy = function() Bitset$new(from = bitset_copy(self$.bitset)),
- #' @description return an integer vector of the elements
- #' stored in this bitset.
+ #' `r bitset_method_doc("to_vector", "return an integer vector of the elements stored in this bitset.")`
to_vector = function() bitset_to_vector(self$.bitset)
)
+
class(self) <- 'Bitset'
self
}
diff --git a/man/Bitset.Rd b/man/Bitset.Rd
index 21be2b3..d129926 100644
--- a/man/Bitset.Rd
+++ b/man/Bitset.Rd
@@ -1,35 +1,8 @@
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/bitset.R
-\docType{data}
\name{Bitset}
\alias{Bitset}
\title{A Bitset Class}
-\format{
-An object of class \code{list} of length 1.
-}
-\usage{
-Bitset
-}
-\arguments{
-\item{size}{the size of the bitset.}
-
-\item{from}{pointer to an existing IterableBitset to use; if \code{NULL}
-make empty bitset, otherwise copy existing bitset.}
-
-\item{v}{an integer vector of elements (not indices) to remove.}
-
-\item{inplace}{whether to overwrite the current bitset, default = TRUE}
-
-\item{other}{the other bitset.}
-
-\item{rate}{the success probability for keeping each element, can be
-a single value for all elements or a vector of unique
-probabilities for keeping each element.}
-
-\item{k}{the number of items in the bitset to keep. The selection of
-these k items from N total items in the bitset is random, and
-k should be chosen such that \eqn{0 \le k \le N}.}
-}
\description{
This is a data structure that compactly stores the presence of
integers in some finite set (\code{max_size}), and can
@@ -40,36 +13,157 @@ if you would like to perform an operation without destroying your current bitset
This class is defined as a named list for performance reasons, but for most
intents and purposes it behaves just like an R6 class.
+}
+\section{Methods}{
+\if{html}{\out{
}}
+\subsection{Method \code{new()}}{
create a bitset.
-
+\subsection{Usage}{
+\preformatted{Bitset$new(size, from)}
+}
+\subsection{Arguments}{
+\describe{
+\item{\code{size}}{the size of the bitset.}
+\item{\code{from}}{pointer to an existing IterableBitset to use; if \code{NULL} make empty bitset, otherwise copy existing bitset.}
+}
+}
+}
+\if{html}{\out{
}}
+\subsection{Method \code{insert()}}{
insert into the bitset.
-
-remove from the bitset.
-
+\subsection{Usage}{
+\preformatted{Bitset$insert(v)}
+}
+\subsection{Arguments}{
+\describe{
+\item{\code{v}}{an integer vector of elements to insert.}
+}
+}
+}
+\if{html}{\out{
}}
+\subsection{Method \code{remove()}}{
+insert from the bitset.
+\subsection{Usage}{
+\preformatted{Bitset$remove(v)}
+}
+\subsection{Arguments}{
+\describe{
+\item{\code{v}}{an integer vector of elements (not indices) to remove.}
+}
+}
+}
+\if{html}{\out{
}}
+\subsection{Method \code{clear()}}{
clear the bitset.
-
+\subsection{Usage}{
+\preformatted{Bitset$clear()}
+}
+}
+\if{html}{\out{
}}
+\subsection{Method \code{size()}}{
get the number of elements in the set.
-
+\subsection{Usage}{
+\preformatted{Bitset$size()}
+}
+}
+\if{html}{\out{
}}
+\subsection{Method \code{or()}}{
to "bitwise or" or union two bitsets.
-
+\subsection{Usage}{
+\preformatted{Bitset$or(other)}
+}
+\subsection{Arguments}{
+\describe{
+\item{\code{other}}{the other bitset.}
+}
+}
+}
+\if{html}{\out{
}}
+\subsection{Method \code{and()}}{
to "bitwise and" or intersect two bitsets.
-
+\subsection{Usage}{
+\preformatted{Bitset$and(other)}
+}
+\subsection{Arguments}{
+\describe{
+\item{\code{other}}{the other bitset.}
+}
+}
+}
+\if{html}{\out{
}}
+\subsection{Method \code{not()}}{
to "bitwise not" or complement a bitset.
-
-to "bitwise xor" or get the symmetric difference of two bitset
-(keep elements in either bitset but not in their intersection).
-
-Take the set difference of this bitset with another
-(keep elements of this bitset which are not in \code{other}).
-
+\subsection{Usage}{
+\preformatted{Bitset$not(inplace)}
+}
+\subsection{Arguments}{
+\describe{
+\item{\code{inplace}}{whether to overwrite the current bitset, default = TRUE}
+}
+}
+}
+\if{html}{\out{
}}
+\subsection{Method \code{xor()}}{
+to "bitwise xor" get the symmetric difference of two bitset (keep elements in either bitset but not in their intersection).
+\subsection{Usage}{
+\preformatted{Bitset$xor(other)}
+}
+\subsection{Arguments}{
+\describe{
+\item{\code{other}}{the other bitset.}
+}
+}
+}
+\if{html}{\out{
}}
+\subsection{Method \code{set_difference()}}{
+Take the set difference of this bitset with another (keep elements of this bitset which are not in \code{other})
+\subsection{Usage}{
+\preformatted{Bitset$set_difference(other)}
+}
+\subsection{Arguments}{
+\describe{
+\item{\code{other}}{the other bitset.}
+}
+}
+}
+\if{html}{\out{
}}
+\subsection{Method \code{sample()}}{
sample a bitset.
-
-choose k random items in the bitset
-
-returns a copy the bitset.
-
-return an integer vector of the elements
-stored in this bitset.
+\subsection{Usage}{
+\preformatted{Bitset$sample(rate)}
+}
+\subsection{Arguments}{
+\describe{
+\item{\code{rate}}{the success probability for keeping each element, can be a single value for all elements or a vector of unique probabilities for keeping each element.}
+}
+}
+}
+\if{html}{\out{
}}
+\subsection{Method \code{choose()}}{
+choose k random items in the bitset.
+\subsection{Usage}{
+\preformatted{Bitset$choose(k)}
}
-\keyword{datasets}
+\subsection{Arguments}{
+\describe{
+\item{\code{k}}{the number of items in the bitset to keep. The selection of these k items from N total items in the bitset is random, and k should be chosen such that \eqn{0 \le k \le N}.}
+}
+}
+}
+\if{html}{\out{
}}
+\subsection{Method \code{copy()}}{
+returns a copy of the bitset.
+\subsection{Usage}{
+\preformatted{Bitset$copy()}
+}
+}
+\if{html}{\out{
}}
+\subsection{Method \code{to_vector()}}{
+return an integer vector of the elements stored in this bitset.
+\subsection{Usage}{
+\preformatted{Bitset$to_vector()}
+}
+}
+}
+