Updated the vignettes.

R/buildIndex.R

@@ -10,8 +10,16 @@
 #' 
 #' @return
 #' A prebuilt index that can be used in \code{\link{findKNN}} and related functions as the \code{X=} argument.
-#' The type and structure of this index is arbitrary and left to the discretion of the method developer;
-#' however, users should assume that the index is not serializable (i.e., cannot be saved or transferred between processes).
+#' The exact type of the index is not defined, but users should assume that the index is not serializable, i.e., cannot be saved or transferred between processes.
+#'
+#' @details
+#' The type and structure of the index object returned by \code{buildIndex} methods is arbitrary and left to the discretion of the developer.
+#' However, there are a few constraints:
+#' \itemize{
+#' \item It should not be a matrix, as this interferes with dispatch for methods like \code{\link{findKNN}} when \code{X} is just the data matrix.
+#' \item If it is an external pointer, it should refer to a BiocNeighborsPrebuilt object (see \code{system.file("include", "BiocNeighbors.h", package="BiocNeighbors")}.
+#' This allows it to be directly used in methods like \code{\link{findKNN}}.
+#' }
 #' 
 #' @author
 #' Aaron Lun