RPKG-6: adjustments cran review (#23)

* Removed redundant 'for R' from title.

* Update description, version bump from CRAN review comments.

* Explicit return docs on each function as per CRAN review.

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: interface
 Type: Package
-Title: Runtime Type System for R
-Version: 0.1.0
+Title: Runtime Type System
+Version: 0.1.1
 URL: https://github.com/dereckmezquita/interface
 Authors@R: 
     person(given = "Dereck",
@@ -11,7 +11,7 @@ Authors@R:
            comment = c(ORCID = "0000-0002-9307-6762"))
 Author: Dereck Mezquita [aut, cre] (0000-0002-9307-6762)
 Maintainer: Dereck Mezquita <dereck@mezquita.io>
-Description: Provides a runtime type system for R, allowing users to define and implement interfaces, enums, typed data.frame/data.table, as well as typed functions. This package enables stricter type checking and validation, improving code structure, robustness and reliability in R programming.
+Description: Provides a runtime type system, allowing users to define and implement interfaces, enums, typed data.frame/data.table, as well as typed functions. This package enables stricter type checking and validation, improving code structure, robustness and reliability.
 License: MIT + file LICENSE
 Encoding: UTF-8
 VignetteBuilder: knitr

R/enum.R

@@ -5,7 +5,8 @@
 #' which can be used to create enum objects with values restricted to the specified set.
 #'
 #' @param ... The possible values for the enumerated type. These should be unique character strings.
-#' @return A function (enum generator) that creates enum objects of the defined type.
+#' @return A function (enum generator) of class 'enum_generator' that creates enum objects of the defined type.
+#'         The returned function takes a single argument and returns an object of class 'enum'.
 #'
 #' @examples
 #' # Create an enum type for colors
@@ -34,7 +35,7 @@
 #' @export
 enum <- function(...) {
     values <- c(...)
-    
+
     new <- function(value) {
         if (!value %in% values) {
             stop(sprintf("Invalid value. Must be one of: %s", paste(values, collapse = ", ")))
@@ -45,7 +46,7 @@ enum <- function(...) {
             values = values
         ))
     }
-    
+
     class(new) <- c("enum_generator", "function")
     attr(new, "values") <- values
     return(new)
@@ -58,6 +59,8 @@ enum <- function(...) {
 #'
 #' @param x An enum object
 #' @param ... Additional arguments (not used)
+#' @return No return value, called for side effects.
+#'         Prints a string representation of the enum object to the console.
 #' @export
 #'
 #' @examples
@@ -149,6 +152,8 @@ print.enum <- function(x, ...) {
 #'
 #' @param x An enum generator function
 #' @param ... Additional arguments (not used)
+#' @return No return value, called for side effects.
+#'         Prints a string representation of the enum generator to the console.
 #' @export
 #'
 #' @examples

R/fun.R

@@ -4,7 +4,8 @@
 #' Defines a function with specified parameter types and return type. Ensures that the function's arguments and return value adhere to the specified types.
 #'
 #' @param ... Named arguments defining the function parameters and their types, including 'return' for the expected return type(s) and 'impl' for the function implementation.
-#' @return A typed function that enforces type constraints on its parameters and return value.
+#' @return A function of class 'typed_function' that enforces type constraints on its parameters and return value.
+#'         The returned function has the same signature as the implementation function provided in the 'impl' argument.
 #' @details
 #' The `fun` function allows you to define a function with strict type checking for its parameters and return value. 
 #' This ensures that the function receives arguments of the correct types and returns a value of the expected type.
@@ -49,7 +50,7 @@ fun <- function(...) {
     args <- list(...)
     return_type <- args$return
     impl <- args$impl
-    
+
     # Remove 'return' and 'impl' from args
     args$return <- NULL
     args$impl <- NULL
@@ -114,6 +115,9 @@ fun <- function(...) {
 #'
 #' @param x A typed function.
 #' @param ... Additional arguments (not used).
+#' @return No return value, called for side effects.
+#'         Prints a human-readable representation of the typed function to the console,
+#'         showing the argument types and return type.
 #' @export
 #' @examples
 #' # Define a typed function

R/interface.R

@@ -7,7 +7,9 @@
 #' @param ... Named arguments defining the properties and their types or validation functions.
 #' @param validate_on_access Logical, whether to validate properties on access (default: FALSE).
 #' @param extends A list of interfaces that this interface extends.
-#' @return A function to create objects that implement the defined interface.
+#' @return A function of class 'interface' that creates objects implementing the defined interface.
+#'         The returned function takes named arguments corresponding to the interface properties
+#'         and returns an object of class 'interface_object'.
 #' @export
 #'
 #' @examples
@@ -135,6 +137,8 @@ interface <- function(..., validate_on_access = FALSE, extends = list()) {
 #'
 #' @param x An interface object
 #' @param name The name of the property to get
+#' @return The value of the specified property. The class of the returned value
+#'         depends on the property's type as defined in the interface.
 #' @export
 `$.interface_object` <- function(x, name) {
     if (!(name %in% names(attributes(x)$properties))) {
@@ -155,6 +159,7 @@ interface <- function(..., validate_on_access = FALSE, extends = list()) {
 #' @param x An interface object
 #' @param name The name of the property to set
 #' @param value The new value for the property
+#' @return The modified interface object, invisibly.
 #' @export
 `$<-.interface_object` <- function(x, name, value) {
     if (!(name %in% names(attributes(x)$properties))) {
@@ -174,6 +179,8 @@ interface <- function(..., validate_on_access = FALSE, extends = list()) {
 #'
 #' @param x An object implementing an interface
 #' @param ... Additional arguments (not used)
+#' @return No return value, called for side effects.
+#'         Prints a human-readable representation of the interface object to the console.
 #' @export
 print.interface_object <- function(x, ...) {
     cat("Object implementing interface:\n")

R/type.frame.R

@@ -10,7 +10,8 @@
 #' @param row_callback A function to validate and process each row (optional).
 #' @param allow_na Logical, whether to allow NA values (default: TRUE).
 #' @param on_violation Action to take on violation: "error", "warning", or "silent" (default: "error").
-#' @return A function that creates typed data frames.
+#' @return A function that creates typed data frames. When called, this function returns
+#'         an object of class 'typed_frame' (which also inherits from the base frame class used, i.e. data.frame, data.table).
 #' @details
 #' The `type.frame` function defines a blueprint for a data frame, specifying the types of its columns and optional validation rules for its rows. 
 #' When a data frame is created or modified using this blueprint, it ensures that all data adheres to the specified rules.
@@ -315,6 +316,9 @@ wrap_fun_in_all <- function(user_fun) {
 #'
 #' @param x A typed data frame.
 #' @param ... Additional arguments passed to print.
+#' @return No return value, called for side effects.
+#'         Prints a summary of the typed data frame to the console, including its dimensions,
+#'         column specifications, frame properties, and a preview of the data.
 #' @importFrom utils head
 #' @export
 print.typed_frame <- function(x, ...) {
@@ -372,7 +376,8 @@ get_type_description <- function(col_type) {
 #'
 #' @param ... Typed data frames to combine.
 #' @param deparse.level See \code{\link[base]{rbind}}.
-#' @return The combined typed data frame.
+#' @return The combined typed data frame. The returned object is of class 'typed_frame'
+#'         and inherits all properties (column types, validation rules, etc.) from the first data frame in the list.
 #' @details
 #' This version of \code{rbind} for \code{typed_frame} performs extra type checking and row validation to ensure consistency and adherence to specified rules. 
 #' Refer to the base \code{rbind} documentation for additional details on combining data frames: \code{\link[base]{rbind}}.

R/validate_property.R

@@ -6,8 +6,28 @@
 #' @param name The name of the property being validated.
 #' @param value The value of the property.
 #' @param validator The expected type or a custom validation function.
-#' @return NULL if the validation passes, otherwise an error message.
+#' @return Returns NULL if the validation passes, otherwise returns a character string
+#'         containing an error message describing why the validation failed.
+#' @details
+#' This function supports various types of validators:
+#' - Enum generators
+#' - Lists of multiple allowed types
+#' - Interface objects
+#' - Built-in R types (character, numeric, logical, integer, double, complex)
+#' - data.table and data.frame types
+#' - Custom validation functions
 #'
+#' @examples
+#' \dontrun{
+#' # Validate a numeric property
+#' validate_property("age", 30, numeric)  # Returns NULL
+#' validate_property("age", "thirty", numeric)  # Returns error message
+#'
+#' # Validate with a custom function
+#' is_even <- function(x) x %% 2 == 0
+#' validate_property("even_number", 4, is_even)  # Returns NULL
+#' validate_property("even_number", 3, is_even)  # Returns error message
+#' }
 validate_property <- function(name, value, validator) {
     if (inherits(validator, "enum_generator")) {
         # Enum validation is handled by the enum generator itself
@@ -80,4 +100,4 @@ validate_property <- function(name, value, validator) {
     }
 
     return(NULL)
-}
+}

README.Rmd

@@ -336,4 +336,4 @@ This package is licensed under the MIT License.
 
 If you use this package in your research or work, please cite it as:
 
-Mezquita, D. (2024). interface: A Runtime Type System for R. R package version 0.1.0. https://github.com/dereckmezquita/interface
+Mezquita, D. (2024). interface: A Runtime Type System. R package version 0.1.0. https://github.com/dereckmezquita/interface

inst/CITATION

@@ -1,13 +1,13 @@
 bibentry(
   bibtype  = "Manual",
-  title    = "interface: A Runtime Type System for R",
+  title    = "interface: A Runtime Type System",
   author   = "Dereck Mezquita",
   year     = "2024",
   note     = "R package version 0.1.0",
   url      = "https://github.com/dereckmezquita/interface",
   textVersion = paste(
     "Mezquita, D. (2024).",
-    "interface: A Runtime Type System for R.",
+    "interface: A Runtime Type System.",
     "R package version 0.1.0.",
     "https://github.com/dereckmezquita/interface"
   )