1

Because it is on the list of Internal Generic Functions, I know that rep is an internal generic function. Could this fact have been derived by only reading the documentation for rep? I have located the following two relevant-looking sections:

rep replicates the values in x. It is a generic function, and the (internal) default method is described here.

For the internal default method these can include:

Do either of these specifically tell the reader that rep is an internal generic function?

To be totally clear, I'm asking about the terminology that is used in these extracts. I'm not an expert on R's terminology, so what I'm asking is about what is implied by the words that they've used. For example, if the R documentation says that a function "is generic" and has an "internal default method", does that mean that the function is therefore an internal generic function?

A link to some sort of glossary of R terms, or the relevant section in one of the R manuals, would be a very strong component of a good answer. A simple yes or no will probably not suffice.

J. Mini
  • 1,868
  • 1
  • 9
  • 38
  • 1
    You could have a loojk at [R Internals](https://cran.r-project.org/doc/manuals/r-release/R-ints.html) and search for `list of primitive functions` – Waldi Feb 23 '21 at 18:10
  • @Waldi Are you sure that helps? All that I saw there was a list claiming "_The following functions are primitive for efficiency reasons:_" that included `rep`. I don't think that really tells us any more than my original link to the list of Internal Generic Functions. Both establish the existence of a special class of misbehaving functions and that `rep` is a member of said class, but I don't believe that either answer the terminological question that I'm asking. – J. Mini Feb 23 '21 at 18:26
  • @Mini, this is the reference, and I agree it doesn't really answer the question, that's why I didn't use this as an answer, just a possibly useful comment. – Waldi Feb 23 '21 at 18:49
  • 3
    What exactly is your goal? Why do you care if the help file points out *how* it is implemented? Documentation isn't necessarily supposed to tell you about the implementation unless it's incredibly relevant to the function. If you want to know about the implementation... look at the code. – Dason Feb 23 '21 at 19:04
  • 1
    Even the code might not adequately address your curiosity. Sometimes, the only way to know *why* a function was developed as a primitive or a generic or whatever is to talk with the developers that wrote it. I have to agree with Dason, though, why do you need to resolve this? If it's just curiosity, good luck. If there's some performance or integration problem you're experiencing, then that's a different issue (best discussed with details). – r2evans Feb 23 '21 at 21:10
  • 2
    Following up on @r2evans comment, there are far more R Core members, involved in development and design of R, hanging on the [R-help mailing list](https://stat.ethz.ch/mailman/listinfo/r-help) than here, so some "_why_ questions" on code and docs may be worth posting there. I don't claim that this particular question would be better suited there, just a heads-up. Cheers. – Henrik Feb 23 '21 at 22:47
  • @Dason My goal is simply to check if I understand R's terminology. I care about this because it will help me understand more R documentation than I currently do. This isn't a "why" question. – J. Mini Feb 23 '21 at 23:12

1 Answers1

4

Firstly, I think you would benefit from the following resource (15.7 Generic-Function OO, https://homerhanumat.github.io/r-notes/generic-function-oo.html).

Secondly, some definitions (extracted from https://homerhanumat.github.io/r-notes/glossary-12.html and https://colinfay.me/r-internals/internal-vs-primitive.html):

Generic function: "A function that dispatches an input object to one of a number of method-functions, based on the class of the input".

Generic-Function OO: "A type of object-oriented programming in which tasks are performed by generic functions. The method used to perform a particular task is determined by the class of the input object".

Primitive and Internal functions: "C code compiled into R at build time can be called directly in what are termed primitives or via the .Internal interface, which is very similar to the .External interface except in syntax".

Thus, we can say that:

Internal Generic function: Primitive and internal functions that are generic (e.g. function that dispatches an input object to one of a number of method-functions, based on the class of the input).

Now, answering your questions:

a) Is the documentation clear?

"It is a generic function, and the (internal) default method is described here". It clearly states that rep is a generic function. The "(internal)" sort of glimpses that it is a internal/primitive function. What is the need for the parenthesis around internal? I actually do not know. It would certainly be clearer if it stated: "rep falls under the category of internal generic functions (see InternalMethods). Details on the default methods are described here". However, for rep.int and rep_len it is a bit clearer ("Internally, they are generic"). Writing good documentation is always hard!

b) How to empirically find out whether a function is internal generic

Relying on documentation does not always guarantee success. This is certainly true for the huge diversity of R-packages offered at CRAN. But, this topic is not just a random R-package but low level R-programming language. Reading rep's source code you, we can confirm that rep is a primitive function:

> rep
function (x, ...)  .Primitive("rep")

And by running the following, we can confirm that rep is a generic function:

> methods(rep)
[1] rep.bibentry*       rep.Date            rep.factor          rep.numeric_version rep.POSIXct        
[6] rep.POSIXlt         rep.roman*

Therefore, rep must be an internal generic function. Just to provide a negative control (the output of methods for a function that is not generic), see below:

> methods(diag)
no methods found

c) R-CRAN resources

Finally, CRAN did do a great job compiling the definition of the R-programming language here (cran.r-project.org/doc/manuals/r-release/R-lang.html); There is much more information on section "5 Object-oriented programming". But resources provided above are a bit more didactical. CRAN offers several manuals which may be of your interest (cran.r-project.org/manuals.html).

Henrik
  • 65,555
  • 14
  • 143
  • 159
Ventrilocus
  • 1,408
  • 3
  • 13
  • This seems to be almost acceptable. I just have two small objections. 1) You have spent a lot of time telling the reader what to do when the documentation fails them, but have only devoted one sentence to the actual question of "_has the documentation failed us?_". Spelling out that the documentation has failed us, perhaps by reusing the quotes in the question, will likely be helpful. 2) It is concerning that this answer required links to outside of R's documentation. One would hope that the required terms are defined in R's docs. But hey, if they aren't, then they aren't. – J. Mini Mar 04 '21 at 18:16
  • 1
    Personally, no documentation is ever complete. This is certainly true for the huge diversity of R-packages offered at CRAN. But, this topic is not just a random R-package but low level R-programming language. Though, must say, CRAN did do a great job compiling the definition of the R-programming language here (https://cran.r-project.org/doc/manuals/r-release/R-lang.html); go to section "5 Object-oriented programming". But other resources can be a bit more didactical (hence my suggestions). CRAN offers several manuals (https://cran.r-project.org/manuals.html) which may be of your interest – Ventrilocus Mar 05 '21 at 09:25
  • Quite right. The rigorous details are probably somewhere in the R Internals manual, but I've not been able to find them. That's more than enough to cover my second objection, but I'm not so sure about my first. – J. Mini Mar 05 '21 at 12:19
  • "It is a generic function, and the (internal) default method is described here". It clearly states that "rep" is a generic function. The "(internal)" sort of glimpses that it is a internal/primitive function. What is the need for the parenthesis around internal? I actually do not know. It would certainly be clearer if it stated: "rep falls under the category of internal generic functions (see InternalMethods). Details on the default methods are described here". However, for rep.int and rep_len it is a bit clearer ("Internally, they are generic"). Writing good documentation is always hard! – Ventrilocus Mar 05 '21 at 13:24
  • Fit that in to your answer somewhere and all my complains will be addressed. Give it a week and you'll probably have the bounty. – J. Mini Mar 05 '21 at 13:31