Document classes (#36)

* fixes to vignette

* export class docs

* rename vignette

* add more roxygen

* add instance docs

* document module

* add registry documentation

R/Field.R

@@ -1,13 +1,15 @@
 #' @title Field
 #'
-#' @noRd
-#'
 #' @description
 #' A field in a registry.
 Field <- R6::R6Class( # nolint object_name_linter
   "Field",
   cloneable = FALSE,
   public = list(
+    #' @description
+    #' Creates an instance of this R6 class. This class should not be instantiated directly,
+    #' but rather by connecting to a LaminDB instance using the [connect()] function.
+    #'
     #' @param type The type of the field. Can be one of:
     #'   "IntegerField", "JSONField", "OneToOneField", "SmallIntegerField",
     #'   "BigIntegerField", "AutoField", "BigAutoField", "BooleanField", "TextField",
@@ -94,47 +96,58 @@ Field <- R6::R6Class( # nolint object_name_linter
     .related_module_name = NULL
   ),
   active = list(
-    #' @return The type of the field.
+    #' @field type (`character(1)`)\cr
+    #' The type of the field.
     type = function() {
       private$.type
     },
-    #' @return The through value of the field.
+    #' @field through (`list()` or `NULL`)\cr
+    #' The through value of the field.
     through = function() {
       private$.through
     },
-    #' @return The field name.
+    #' @field field_name (`character(1)`)\cr
+    #' The field name.
     field_name = function() {
       private$.field_name
     },
-    #' @return The registry name.
+    #' @field registry_name (`character(1)`)\cr
+    #' The registry name.
     registry_name = function() {
       private$.registry_name
     },
-    #' @return The column name.
+    #' @field column_name (`character(1)`)\cr
+    #' The column name.
     column_name = function() {
       private$.column_name
     },
-    #' @return The module name.
+    #' @field module_name (`character(1)`)\cr
+    #' The module name.
     module_name = function() {
       private$.module_name
     },
-    #' @return Whether the field is a link table.
+    #' @field is_link_table (`logical(1)`)\cr
+    #' Whether the field is a link table.
     is_link_table = function() {
       private$.is_link_table
     },
-    #' @return The relation type.
+    #' @field relation_type (`character(1)` or `NULL`)\cr
+    #' The relation type. Can be one of: "one-to-many", "many-to-one", "many-to-many".
     relation_type = function() {
       private$.relation_type
     },
-    #' @return The related field name.
+    #' @field related_field_name (`character(1)` or `NULL`)\cr
+    #' The related field name.
     related_field_name = function() {
       private$.related_field_name
     },
-    #' @return The related registry name.
+    #' @field related_registry_name (`character(1)` or `NULL`)\cr
+    #' The related registry name.
     related_registry_name = function() {
       private$.related_registry_name
     },
-    #' @return The related module name.
+    #' @field related_module_name (`character(1)` or `NULL`)\cr
+    #' The related module name.
     related_module_name = function() {
       private$.related_module_name
     }

R/Instance.R

@@ -63,14 +63,43 @@ create_instance <- function(instance_settings) {
 
 #' @title Instance
 #'
-#' @noRd
-#'
 #' @description
-#' A LaminDB instance.
+#' Connect to a LaminDB instance using the [connect()] function.
+#' The instance object provides access to the modules and registries
+#' of the instance.
+#'
+#' @details
+#' Note that by connecting to an instance via [connect()], you receive
+#' a "richer" version of the Instance class documented here, providing
+#' direct access to all core registries and additional modules.
+#' See the vignette on "Package Architecture" for more information:
+#' `vignette("architecture", package = "laminr")`.
+#'
+#' @examples
+#' \dontrun{
+#' # Connect to an instance
+#' db <- connect("laminlabs/cellxgene")
+#'
+#' # fetch an artifact
+#' artifact <- db$Artifact$get("KBW89Mf7IGcekja2hADu")
+#'
+#' # describe the artifact
+#' artifact$describe()
+#'
+#' # view field
+#' artifact$id
+#'
+#' # load dataset
+#' artifact$load()
+#' }
 Instance <- R6::R6Class( # nolint object_name_linter
   "Instance",
   cloneable = FALSE,
   public = list(
+    #' @description
+    #' Creates an instance of this R6 class. This class should not be instantiated directly,
+    #' but rather by connecting to a LaminDB instance using the [connect()] function.
+    #'
     #' @param settings The settings for the instance
     #' @param api The API for the instance
     #' @param schema The schema for the instance
@@ -92,24 +121,40 @@ Instance <- R6::R6Class( # nolint object_name_linter
       ) |>
         set_names(names(schema))
     },
-    #' Get the modules for the instance.
+    #' @description Get the modules for the instance.
+    #'
+    #' @return A list of [Module] objects.
     get_modules = function() {
       private$.module_classes
     },
-    #' Get a module by name.
+    #' @description Get a module by name.
+    #'
+    #' @param module_name The name of the module.
+    #'
+    #' @return The [Module] object.
     get_module = function(module_name) {
       # todo: assert module exists
       private$.module_classes[[module_name]]
     },
-    #' Get the names of the modules. Example: `c("core", "bionty")`.
+    #' @description Get the names of the modules. Example: `c("core", "bionty")`.
+    #'
+    #' @return A character vector of module names.
     get_module_names = function() {
       names(private$.module_classes)
     },
-    #' Get instance settings.
+    #' @description Get instance settings.
+    #'
+    #' Note: This method is intended for internal use only and may be removed in the future.
+    #'
+    #' @return The settings for the instance.
     get_settings = function() {
       private$.settings
     },
-    #' Get instance API.
+    #' @description Get instance API.
+    #'
+    #' Note: This method is intended for internal use only and may be removed in the future.
+    #'
+    #' @return The API for the instance.
     get_api = function() {
       private$.api
     },
@@ -118,7 +163,6 @@ Instance <- R6::R6Class( # nolint object_name_linter
     #'
     #' @param style Logical, whether the output is styled using ANSI codes
     print = function(style = TRUE) {
-
       registries <- self$get_module("core")$get_registries()
 
       is_link_table <- purrr::map(registries, "is_link_table") |>
@@ -206,11 +250,13 @@ Instance <- R6::R6Class( # nolint object_name_linter
       }
 
       key_value_strings <- make_key_value_strings(
-        mapping, quote_strings = FALSE
+        mapping,
+        quote_strings = FALSE
       )
 
       make_class_string(
-        private$.settings$name, key_value_strings, style = style
+        private$.settings$name, key_value_strings,
+        style = style
       )
     }
   ),

R/InstanceAPI.R

@@ -8,6 +8,10 @@ InstanceAPI <- R6::R6Class( # nolint object_name_linter
   "API",
   cloneable = FALSE,
   public = list(
+    #' @description
+    #' Creates an instance of this R6 class. This class should not be instantiated directly,
+    #' but rather by connecting to a LaminDB instance using the [connect()] function.
+    #'
     #' @param instance_settings The settings for the instance
     #' Should have the following fields:
     #'  - id: The ID of the instance

R/InstanceSettings.R

@@ -9,6 +9,10 @@ InstanceSettings <- R6::R6Class( # nolint object_name_linter
   "InstanceSettings",
   cloneable = FALSE,
   public = list(
+    #' @description
+    #' Creates an instance of this R6 class. This class should not be instantiated directly,
+    #' but rather by connecting to a LaminDB instance using the [connect()] function.
+    #'
     #' @param settings A named list of settings for the instance
     initialize = function(settings) {
       expected_keys <- c(

R/Module.R

@@ -44,17 +44,20 @@ create_module <- function(instance, api, module_name, module_schema) {
 
 #' @title Module
 #'
-#' @noRd
-#'
 #' @description
 #' A LaminDB module containing one or more registries.
 Module <- R6::R6Class( # nolint object_name_linter
   "Module",
   cloneable = FALSE,
   public = list(
+    #' @description
+    #' Creates an instance of this R6 class. This class should not be instantiated directly,
+    #' but rather by connecting to a LaminDB instance using the [connect()] function.
+    #'
     #' @param instance The instance the module belongs to.
     #' @param api The API for the instance.
     #' @param module_name The name of the module.
+    #' @param module_schema The schema of the module.
     initialize = function(instance, api, module_name, module_schema) {
       private$.instance <- instance
       private$.api <- api
@@ -74,25 +77,29 @@ Module <- R6::R6Class( # nolint object_name_linter
       ) |>
         set_names(names(module_schema))
     },
-    #' @description
-    #' Get the registries in the module.
+    #' @description Get the registries in the module.
+    #'
+    #' @return A list of [Registry] objects.
     get_registries = function() {
       private$.registry_classes
     },
-    #' @description
-    #' Get a registry by name.
+    #' @description Get a registry by name.
+    #'
+    #' @param registry_name The name of the registry.
+    #'
+    #' @return A [Registry] object.
     get_registry = function(registry_name) {
       private$.registry_classes[[registry_name]]
     },
-    #' @description
-    #' Get the names of the registries in the module. E.g. `c("User", "Artifact")`.
+    #' @description Get the names of the registries in the module. E.g. `c("User", "Artifact")`.
+    #'
+    #' @return A character vector of registry names.
     get_registry_names = function() {
       names(private$.registry_classes)
     },
-    #' @description
-    #' Print a `Module`
+    #' @description Print a `Module`
     #'
-    #' @param style Logical, whether the output is styled using ANSI codes
+    #' @param style Logical, whether the output is styled using ANSI codes.
     print = function(style = TRUE) {
       registries <- self$get_registries()
 
@@ -171,6 +178,7 @@ Module <- R6::R6Class( # nolint object_name_linter
     .registry_classes = NULL
   ),
   active = list(
+    #' @field name (`character(1)`)\cr
     #' Get the name of the module.
     name = function() {
       private$.module_name

R/Record.R

@@ -47,14 +47,16 @@ create_record_class <- function(instance, registry, api) {
 
 #' @title Record
 #'
-#' @noRd
-#'
 #' @description
 #' A record from a registry.
 Record <- R6::R6Class( # nolint object_name_linter
   "Record",
   cloneable = FALSE,
   public = list(
+    #' @description
+    #' Creates an instance of this R6 class. This class should not be instantiated directly,
+    #' but rather by connecting to a LaminDB instance using the [connect()] function.
+    #'
     #' @param instance The instance the record belongs to.
     #' @param registry The registry the record belongs to.
     #' @param api The API for the instance.