When does a package need to use ::: for its own objects

Question

Consider this R package with two functions, one exported and the other internal

hello.R

#' @export
hello <- function() {
  internalFunctions:::hello_internal()
}

hello_internal.R

hello_internal <- function(x){
    print("hello world")
}

NAMESPACE

# Generated by roxygen2 (4.1.1): do not edit by hand

export(hello)

---

When this is checked (devtools::check()) it returns the NOTE

There are ::: calls to the package's namespace in its code. A package
  almost never needs to use ::: for its own objects:
  ‘hello_internal’

---

Question

Given the NOTE says almost never, under what circumstances will a package need to use ::: for its own objects?

---

Extra

I have a very similar related question where I do require the ::: for an internal function, but I don't know why it's required. Hopefully having an answer to this one will solve that one. I have a suspicion that unlocking the environment is doing something I'm not expecting, and thus having to use ::: on an internal function.

If they are considered duplicates of each other I'll delete the other one.

Answer 1

Here is a pseudo-code example, where I think using ::: is the only viable solution:

# R-package with an internal function FInternal() that is called in a foreach loop
FInternal <- function(i) {...}

#' Exported function containing a foreach loop
#' @export
ParallelLoop <- function(is, <other-variables>) {
   foreach(i = is) %dopar% {
      # This fails, because it cannot not locate FInternal, unless it is exported.
      FInternal(i)
      # This works but causes a note:
      PackageName:::FInternal(i)
   }
}

I think the problem here is that the body of the foreach loop is not defined as a function of the package. Hence, when executed on a worker process, it is not treated as a code belonging to the package and does not have access to the internal objects of the package. I would be glad if someone could suggest an elegant solution for this specific case.

Answer 2

You should never need this in ordinary circumstances. You may need it if you are calling the parent function in an unusual way (for example, you've manually changed its environment, or you're calling it from another process where the package isn't attached).