klmr / klmr/box

Opening documentation through `box::help()` gone wrong for a name re-exported through a parent `__init__.r`, but works when the submodule is qualified directly

Open
#399 0 comments 0 reactions 0 assignees View on GitHub
⚠️ bug
Dominant language
R
Stars
979
Forks
49
PR merge metrics
No merged PRs in 30d

Description

### Error description

Is this a known bug? I will file an issue here just in case. You see, when a function is re-exported from a nested module through its parent `__init__.r` (via a `#' @export` on a `box::use()` declaration or `box::export()` on some instance), calling the re-exported function through the parent module works fine, but `box::help()` cannot find its documentation. Qualifying the import path down to the actual submodule where the function is defined makes `box::help()` work as expected.

Here's an example directory structure:

```
module/
__init__.R
folder1/
__init__.R
df.R
types.R
folder2/
__init__.R
df.R
types.R
folder3/
__init__.R
types.R
scripts1.R
scripts2.R
```

The the following codes:

1. `module/__init__.R`:

``` r
#' @export
box::use(
./folder1,
./folder2,
./folder3,
./scripts1,
./scripts2[fn1],
)
```

2. `module/scripts2.R` (relevant excerpt):

``` r
#' Do a thing
#'
#' @param x a value
#' @export
fn1 = function(x) {
x
}
```

And when I use:

``` r
# Import through the parent module
box::use(./module[fn1])

# Works as it is
fn1(1) # [1] 1

# Fails to find/display documentation
box::help(fn1)
## Error in box::help(fn1) :
## no documentation available for “fn1” in module “./module”

# Import qualified directly to the submodule instead
box::use(./module/scripts2[fn1])

# Documentation is displayed correctly
box::help(fn1)
```

`box::help()` should be able to locate and display the documentation for `fn1` regardless of whether it was imported through the parent module's re-export (`./module[fn1]`) or directly from the submodule where it's defined (`./module/scripts2[fn1]`). Unfortunately, what I got is an opposite. Here, `box::help()` (only) finds the documentation when importing directly from a submodule that defines the name. When imported through the parent module's re-export chain, `box::help()` fails to locate it, even though the function itself works correctly (i.e. this is more of a documentation-lookup issue, not really an export issue since I still can use `fn1()`).

Edit: The examples are just placeholders. I mistyped `fn1` as `walk` (trying to extract `walk` tutorial from `tidytable`)

### R version

```plain text
platform x86_64-w64-mingw32
arch x86_64
os mingw32
crt ucrt
system x86_64, mingw32
status
major 4
minor 5.0
year 2025
month 04
day 11
svn rev 88135
language R
version.string R version 4.5.0 (2025-04-11 ucrt)
nickname How About a Twenty-Six
```

### ‘box’ version

1.2.2

Contributor guide

Open the contributing guide

Research direction

Reproduce the failure with the shown module/__init__.R and scripts2.R layout, comparing box::help(fn1) after ./module[fn1] and ./module/scripts2[fn1]. Trace box::help() and box::use() handling of re-exported names; done means the parent import displays fn1's documentation as the direct submodule import does.

Written by the indexing model from the issue text.

Assessment

Tech stack
r
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.