Namespaces in R packages
RR Problem Overview
How do people learn about giving an R package a namespace? I find the documention in "R Extensions" fine, but I don't really get what is happening when a variable is imported or exported - I need a dummy's guide to these directives.
How do you decide what is exported? Is it just everything that really shouldn't required the pkg:::var syntax? What about imports?
Do imports make it easier to ensure that your use of other package functions doesn't get confused when function names overlap?
Are there special considerations for S4 classes?
Packages that I'm familiar with that use namespaces such as sp and rgdal are quite complicated - are there simple examples that could make things clearer?
R Solutions
Solution 1 - R
I have a start on an answer on the devtools wiki: http://adv-r.had.co.nz/Namespaces.html
Solution 2 - R
Few years later here....
I consolidated findings from Chambers, other StackOverflow posts, and lots of tinkering in R: http://blog.obeautifulcode.com/R/How-R-Searches-And-Finds-Stuff/
This is less about implementing NAMESPACE/IMPORTS/DEPENDS and more about the purpose of these structures. Answers some of your questions.
Solution 3 - R
The clearest explanation I've read is in John Chambers' [Software for Data Analysis: Programming with R][1], page 103. I don't know of any free online explanations that are better than what you've already found in the R Extensions manual.
[1]: http://www.amazon.com/Software-Data-Analysis-Programming-Statistics/dp/0387759352 "Software for Data Analysis"
Solution 4 - R
You could also pick an easy, small package and follow it.
I semi-randomly looked at digest which is one of my smaller packages. I loads a (small) dynamic library and exports one symbol, the digest() function. Here is the content of the NAMESPACE file:
## package has dynamic library
useDynLib(digest)
## and one and only one core function
export(digest)
Have a look at the rest of the source files and maybe try to read Writing R Extensions alongside looking at the example, and do some experiments.