Should Namespace Calls be Added in Package Function Examples?

[kartikeyakirar]

In many package function examples, the use of namespace calls (pkg::function) varies across packages. Some examples include namespace calls, while others omit them entirely. This lack of consistency raises the question of whether it is beneficial to add namespace calls to package function examples. This discussion aims to explore the advantages of incorporating namespace calls in package function examples.

Points for Discussion:

Consistency and Clarity:

By including namespace calls in package function examples, we can establish consistency across packages. Users will become accustomed to seeing the package namespace preceding the function, which can enhance clarity and improve their understanding.
Namespace calls explicitly indicate the source of the function, enabling users to quickly identify the package from which the function is being called. This reduces confusion and ensures proper attribution.

Improved Debugging:

When troubleshooting or debugging code, having the namespace call in package function examples can be extremely helpful.

Facilitating Learning and Documentation:

For users who are new to a package, including namespace calls in examples can assist in the learning process. Seeing the package namespace alongside the function name reinforces the association between the two, helping users familiarize themselves with the package's functionality.

#' # ADSL example
#'
#' library(nestcolor)
#' ADSL <- teal.modules.general::rADSL
#'
#' app <- teal::init(
#'   data = teal.data::cdisc_data(
#'     teal.data::cdisc_dataset(
#'       "ADSL", ADSL,
#'       code = "ADSL <- teal.modules.general::rADSL"
#'     ),
#'     check = TRUE
#'   ),
#'   modules = teal::modules(
#'     teal.modules.general::tm_a_pca(
#'       "PCA",
#'       dat = teal.transform::data_extract_spec(
#'         dataname = "ADSL",
#'         select = teal.transform::select_spec(
#'           choices = teal.transform::variable_choices(data = ADSL, c("BMRKR1", "AGE", "EOSDY")),
#'           selected = c("BMRKR1", "AGE"),
#'           multiple = TRUE
#'         ),
#'         filter = NULL
#'       ),
#'       ggplot2_args = teal.widgets::ggplot2_args(
#'         labs = list(subtitle = "Plot generated by PCA Module")
#'       )
#'     )
#'   )
#' )
#' if (interactive()) {
#'   shinyApp(app$ui, app$server)
#' }

[kartikeyakirar]

I think this practice, we can provide users with a more seamless and user-friendly experience, ultimately contributing to the overall quality and usability of their packages.

[chlebowa]

I believe it was decided some time ago to attach packages used in examples rather than prefix their functions. This is in line with a lot of existing R documentation. Specifically, nobody ever prefixes the package the example is in. I guess in your example this would be teal.modules.general.

[kartikeyakirar]

yes, this example is from teal.modules.general.

[chlebowa]

Admittedly, some examples use unexported functions from other packages and so they muse use :::, which I am not a fan of, but apparently there is no other way.

[m7pr]

This is rarely used in other R packages outside our family of packages but here in our case I believe it make sense to prefix functions with packages. The main reason is that there are multiple packages used to run the example, hence this is helpful to understand which parts of the flow comes from which supporting package. Also there is one benefit, that if a code is shared, without the calls to library() [as it often happens for new/beginner R users] the code would still work. Lastly, if one of the packages is missing, you see which package is needed to be installed, if missing. I tend to believe people copy examples from online vignettes or forums and that's the use case you see prefixing will help. For regular manual pages it's less visible, as you need to install all Imports of the package to launch the documentation. But keep this online vignettes and forums in mind!