From d72b9b0f1c54a28c9a06574c930830cc7151d0a3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20Ver=C3=ADssimo?=
 <211358+averissimo@users.noreply.github.com>
Date: Thu, 16 Nov 2023 10:58:44 +0100
Subject: [PATCH] docs: improve on some examples

---
 R/join_key.R     |  1 -
 R/join_keys.R    | 86 ++++++++++++++++++++++++++-----------------
 man/join_keys.Rd | 96 ++++++++++++++++++++++++++++--------------------
 3 files changed, 108 insertions(+), 75 deletions(-)

diff --git a/R/join_key.R b/R/join_key.R
index f268170bc..1ce3dcaf9 100644
--- a/R/join_key.R
+++ b/R/join_key.R
@@ -75,7 +75,6 @@ join_key <- function(dataset_1, dataset_2 = dataset_1, keys) {
   )
 }
 
-#' @rdname get_dataset_1
 #' @keywords internal
 get_keys.join_key_set <- function(join_key_set_object) {
   join_key_set_object[[1]][[1]]
diff --git a/R/join_keys.R b/R/join_keys.R
index 38033b8cf..c0504f6b1 100644
--- a/R/join_keys.R
+++ b/R/join_keys.R
@@ -4,16 +4,23 @@
 #'
 #' @description `r lifecycle::badge("stable")`
 #'
-#' @details - `join_keys()`: When called without arguments it will return an
+#' Note that join keys are created symmetrically, that is, if `dat1` and `dat2`
+#' have a join key of `col1`, then 2 join keys are created, `dat1 → dat2` and
+#' `dat2 → dat1`. The only exception is for a primary key.
+#'
+#' @details
+#'
+#' - `join_keys()`: When called without arguments it will return an
 #' empty constructor.
 #' - `join_keys(x)`: When called with a single argument it will return the `join_keys`
 #' object contained in `x` (if it contains a `join_keys` object).
 #' - `join_keys(...)`: When called with a single or more `join_key_set` parameters it will
 #' create a new object.
+#' - `[[.join_keys` is the preferred getter for `join_keys` that returns the
+#' relationship between pairs of datasets. It returns `NULL` if there is nor
+#' relationship.
 #'
-#' Note that join keys are created symmetrically, that is, if `dat1` and `dat2`
-#' have a join key of `col1`, then 2 join keys are created, `dat1 → dat2` and
-#' `dat2 → dat1`. The only exception is for a primary key.
+#' @order 1
 #'
 #' @param ... (optional), when no argument is given the empty constructor is called.
 #' Otherwise, when called with only one argument of type: `join_keys` or  `teal_data`
@@ -40,15 +47,14 @@
 #' jk[["dataset_A"]][["dataset_C"]] <- c("col_2" = "col_x", "col_3" = "col_y")
 #' jk
 #'
-#' td <- teal_data(join_keys = join_keys(join_key("a", "b", "c")))
-#' join_keys(td)
+#' # Retrieving a key for relationship pair
 #'
-#' jk <- join_keys()
-#' join_keys(jk)
+#' jk[["dataset_A"]][["dataset_B"]]
 #'
-#' jk <- join_keys()
-#' jk <- c(jk, join_keys(join_key("a", "b", "c")))
-#' jk <- c(jk, join_keys(join_key("a", "b", "c"), join_key("a", "b2", "c")))
+#' # Using a teal_data (which contains a join_keys object)
+#'
+#' td <- teal_data(join_keys = join_keys(join_key("a", "b", "c")))
+#' join_keys(td)
 join_keys <- function(...) {
   if (missing(...)) {
     return(new_join_keys())
@@ -89,9 +95,10 @@ join_keys.default <- function(...) {
 }
 
 #' @rdname join_keys
+#'
 #' @details
-#' The setter assignment `join_keys(obj) <- ...` will merge obj and `...` if obj
-#' is not empty.
+#' - "`join_keys(obj) <- value`" will set the `join_keys` in object with `value`.
+#' `value` needs to be an object of class `join_keys` or `join_key_set`.
 #'
 #' @param x (`join_keys`) empty object to set the new relationship pairs.
 #' @param value (`join_key_set` or list of `join_key_set`) relationship pairs to add
@@ -109,9 +116,6 @@ join_keys.default <- function(...) {
 #'
 #' # Using the setter (assignment) ----
 #'
-#' jk <- join_keys()
-#' join_keys(jk) <- join_keys(join_keys(jk), join_key("ds3", "ds4", "some_col2"))
-#'
 #' join_keys(jk)[["ds1"]][["ds3"]] <- "some_col3"
 #' jk
 `join_keys<-.join_keys` <- function(x, value) {
@@ -139,7 +143,9 @@ join_keys.default <- function(...) {
 #'
 #' @examples
 #'
-#' c(join_keys(join_key("a", "b", "c")), join_keys(join_key("a", "d2", "c")))
+#' # Merging multiple `join_keys`
+#'
+#' jk_merged <- c(jk, join_keys(join_key("dataset_D", "dataset_E", "col_2")))
 c.join_keys <- function(...) {
   join_keys_obj <- rlang::list2(...)[[1]]
   x <- rlang::list2(...)[-1]
@@ -163,7 +169,13 @@ c.join_keys <- function(...) {
 #'
 #' @examples
 #'
-#' c(join_key("a", "b", "c"), join_keys(join_key("a", "d2", "c")))
+#' # Note that you can merge join_keys or a single join_key_set
+#'
+#' jk_merged <- c(
+#'   jk_merged,
+#'   join_key("dataset_A", "dataset_F", "col_a"),
+#'   join_key("dataset_O", "dataset_G", "col_g")
+#' )
 c.join_key_set <- function(...) {
   c.join_keys(...)
 }
@@ -206,8 +218,11 @@ c.join_key_set <- function(...) {
 }
 
 #' @rdname join_keys
+#'
 #' @details
-#' Getter for `join_keys` that returns the relationship between pairs of datasets.
+#' - `[.join_keys` can be used to return a subset of relationship pairs. It will
+#' retrieve the primary keys of the selected elements and its parents (along with)
+#' the relationship keys between the selected elements and their parents.
 #'
 #' @param i index specifying elements to extract or replace. Index should be a
 #' a character vector, but it can also take numeric, logical, `NULL` or missing.
@@ -221,9 +236,10 @@ c.join_key_set <- function(...) {
 #'
 #' # Getter for join_keys ----
 #'
-#' jk <- join_keys()
-#' jk[["ds1"]][["ds2"]] <- "some_col"
-#' jk[["ds1"]][["ds3"]] <- "some_col2"
+#' jk <- join_keys(
+#'   join_key("ds1", "ds2", "some_col"),
+#'   join_key("ds1", "ds3", "some_col2")
+#' )
 #'
 #' jk["ds1"]
 #' jk[1:2]
@@ -297,7 +313,7 @@ c.join_key_set <- function(...) {
 #' @rdname join_keys
 #'
 #' @details
-#' `[<-` is not a supported operation for `join_keys`.
+#' - `[<-` is not a supported operation for `join_keys`.
 #'
 #' @export
 `[<-.join_keys` <- function(x, i, value) {
@@ -305,21 +321,23 @@ c.join_key_set <- function(...) {
 }
 
 #' @rdname join_keys
-#' @export
-#' @examples
 #'
-#' jk <- join_keys()
-#' jk[["ds1"]] <- list()
-#' jk[["ds2"]][["ds3"]] <- "key"
+#' @order 3
 #'
-#' jk <- join_keys()
-#' jk[["ds1"]] <- list()
-#' jk[["ds2"]][["ds3"]] <- "key"
-#' jk[["ds4"]] <- list(ds5 = "new")
+#' @details
+#' - `[[<-` is the preferred method to replace or assign new relationship pair to an
+#' existing `join_keys` object.
+#' - `join_keys(obj)[[dataset_1]] <- value` can also be used to assign a relationship
+#' pair to an `obj` that contains a `join_keys`, such as itself or a `teal_data`
+#' object.
+#'
+#' @export
+#' @examples
 #'
 #' jk <- join_keys()
-#' jk[["ds2"]][["ds3"]] <- "key"
-#' jk[["ds2"]][["ds3"]] <- NULL
+#' jk[["dataset_A"]][["dataset_B"]] <- "key"
+#' jk[["dataset_C"]] <- list(dataset_A = "key_2", dataset_B = "key_3")
+#' jk[["dataset_A"]][["dataset_C"]] <- NULL # removes key
 #'
 #' jk
 `[[<-.join_keys` <- function(x, i, value) {
diff --git a/man/join_keys.Rd b/man/join_keys.Rd
index 988cf7ea5..8e43beddc 100644
--- a/man/join_keys.Rd
+++ b/man/join_keys.Rd
@@ -2,6 +2,7 @@
 % Please edit documentation in R/join_keys.R
 \name{join_keys}
 \alias{join_keys}
+\alias{[[<-.join_keys}
 \alias{join_keys.join_keys}
 \alias{join_keys.teal_data}
 \alias{join_keys.TealData}
@@ -13,13 +14,14 @@
 \alias{c.join_key_set}
 \alias{[.join_keys}
 \alias{[<-.join_keys}
-\alias{[[<-.join_keys}
 \alias{format.join_keys}
 \alias{print.join_keys}
 \title{Create a \code{join_keys} out of a list of \code{join_key_set} objects}
 \usage{
 join_keys(...)
 
+\method{[[}{join_keys}(x, i) <- value
+
 \method{join_keys}{join_keys}(...)
 
 \method{join_keys}{teal_data}(...)
@@ -42,8 +44,6 @@ join_keys(x) <- value
 
 \method{[}{join_keys}(x, i) <- value
 
-\method{[[}{join_keys}(x, i) <- value
-
 \method{format}{join_keys}(x, ...)
 
 \method{print}{join_keys}(x, ...)
@@ -57,12 +57,12 @@ constructed from the arguments.}
 
 \item{x}{(\code{join_keys}) empty object to set the new relationship pairs.}
 
-\item{value}{(\code{join_key_set} or list of \code{join_key_set}) relationship pairs to add
-to \code{join_keys} list.}
-
 \item{i}{index specifying elements to extract or replace. Index should be a
 a character vector, but it can also take numeric, logical, \code{NULL} or missing.}
 
+\item{value}{(\code{join_key_set} or list of \code{join_key_set}) relationship pairs to add
+to \code{join_keys} list.}
+
 \item{keep_all_foreign_keys}{(\code{logical}) flag that keeps foreign keys and other
 datasets even if they are not a parent of the selected dataset.}
 }
@@ -71,6 +71,10 @@ datasets even if they are not a parent of the selected dataset.}
 }
 \description{
 \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}}
+
+Note that join keys are created symmetrically, that is, if \code{dat1} and \code{dat2}
+have a join key of \code{col1}, then 2 join keys are created, \verb{dat1 → dat2} and
+\verb{dat2 → dat1}. The only exception is for a primary key.
 }
 \details{
 \itemize{
@@ -80,18 +84,33 @@ empty constructor.
 object contained in \code{x} (if it contains a \code{join_keys} object).
 \item \code{join_keys(...)}: When called with a single or more \code{join_key_set} parameters it will
 create a new object.
+\item \verb{[[.join_keys} is the preferred getter for \code{join_keys} that returns the
+relationship between pairs of datasets. It returns \code{NULL} if there is nor
+relationship.
 }
 
-Note that join keys are created symmetrically, that is, if \code{dat1} and \code{dat2}
-have a join key of \code{col1}, then 2 join keys are created, \verb{dat1 → dat2} and
-\verb{dat2 → dat1}. The only exception is for a primary key.
+\itemize{
+\item \verb{[[<-} is the preferred method to replace or assign new relationship pair to an
+existing \code{join_keys} object.
+\item \code{join_keys(obj)[[dataset_1]] <- value} can also be used to assign a relationship
+pair to an \code{obj} that contains a \code{join_keys}, such as itself or a \code{teal_data}
+object.
+}
 
-The setter assignment \code{join_keys(obj) <- ...} will merge obj and \code{...} if obj
-is not empty.
+\itemize{
+\item "\code{join_keys(obj) <- value}" will set the \code{join_keys} in object with \code{value}.
+\code{value} needs to be an object of class \code{join_keys} or \code{join_key_set}.
+}
 
-Getter for \code{join_keys} that returns the relationship between pairs of datasets.
+\itemize{
+\item \verb{[.join_keys} can be used to return a subset of relationship pairs. It will
+retrieve the primary keys of the selected elements and its parents (along with)
+the relationship keys between the selected elements and their parents.
+}
 
-\verb{[<-} is not a supported operation for \code{join_keys}.
+\itemize{
+\item \verb{[<-} is not a supported operation for \code{join_keys}.
+}
 }
 \examples{
 # Setting join keys ----
@@ -108,21 +127,24 @@ jk[["dataset_A"]][["dataset_B"]] <- c("col_1" = "col_a")
 jk[["dataset_A"]][["dataset_C"]] <- c("col_2" = "col_x", "col_3" = "col_y")
 jk
 
+# Retrieving a key for relationship pair
+
+jk[["dataset_A"]][["dataset_B"]]
+
+# Using a teal_data (which contains a join_keys object)
+
 td <- teal_data(join_keys = join_keys(join_key("a", "b", "c")))
 join_keys(td)
 
 jk <- join_keys()
-join_keys(jk)
+jk[["dataset_A"]][["dataset_B"]] <- "key"
+jk[["dataset_C"]] <- list(dataset_A = "key_2", dataset_B = "key_3")
+jk[["dataset_A"]][["dataset_C"]] <- NULL # removes key
 
-jk <- join_keys()
-jk <- c(jk, join_keys(join_key("a", "b", "c")))
-jk <- c(jk, join_keys(join_key("a", "b", "c"), join_key("a", "b2", "c")))
+jk
 
 # Using the setter (assignment) ----
 
-jk <- join_keys()
-join_keys(jk) <- join_keys(join_keys(jk), join_key("ds3", "ds4", "some_col2"))
-
 join_keys(jk)[["ds1"]][["ds3"]] <- "some_col3"
 jk
 
@@ -134,32 +156,26 @@ join_keys(td)[["ds2"]][["ds2"]] <- "key2"
 join_keys(td) <- c(join_keys(td), join_keys(join_key("ds3", "ds2", "key3")))
 join_keys(td)
 
-c(join_keys(join_key("a", "b", "c")), join_keys(join_key("a", "d2", "c")))
+# Merging multiple `join_keys`
+
+jk_merged <- c(jk, join_keys(join_key("dataset_D", "dataset_E", "col_2")))
+
+# Note that you can merge join_keys or a single join_key_set
 
-c(join_key("a", "b", "c"), join_keys(join_key("a", "d2", "c")))
+jk_merged <- c(
+  jk_merged,
+  join_key("dataset_A", "dataset_F", "col_a"),
+  join_key("dataset_O", "dataset_G", "col_g")
+)
 
 # Getter for join_keys ----
 
-jk <- join_keys()
-jk[["ds1"]][["ds2"]] <- "some_col"
-jk[["ds1"]][["ds3"]] <- "some_col2"
+jk <- join_keys(
+  join_key("ds1", "ds2", "some_col"),
+  join_key("ds1", "ds3", "some_col2")
+)
 
 jk["ds1"]
 jk[1:2]
 jk[c("ds1", "ds2")]
-
-jk <- join_keys()
-jk[["ds1"]] <- list()
-jk[["ds2"]][["ds3"]] <- "key"
-
-jk <- join_keys()
-jk[["ds1"]] <- list()
-jk[["ds2"]][["ds3"]] <- "key"
-jk[["ds4"]] <- list(ds5 = "new")
-
-jk <- join_keys()
-jk[["ds2"]][["ds3"]] <- "key"
-jk[["ds2"]][["ds3"]] <- NULL
-
-jk
 }