[Rd] references to (1) R source code in svn repo within .Rd file and (2) to C source code in comments in R code using .Internal() /.Primitive()

[Peter Ruckdeschel]

Hi R-devels,


recently I wanted to quickly look up a C implementation
in R-Core code in the official subversion repository;

more specifically the code was called from R by means of the .Internal()
interface.

And: yes, I did read Uwe Ligges' article in R News,
R Help Desk: Accessing the sources. R News, 6(4):43-45, October 2006

In the end I succeeded, using grep and the like to search the sources in
R_HOME/src, but I found it rather painful ...

(in particular, if R function foo() is not implemented in file foo.R
 and/or the corresponding C code is not in file ../src/foo.c )


So here my "little" two wishes:

(1) references to R code in the .Rd file

    As all the R source code is accessible through
           https://svn.r-project.org/R
    anyway, why not link to it in .Rd files?

    What about a new optional markup command \URLtoSource with
    one argument (the URL); e.g. inserting to file
        R_HOME/src/library/base/man/sample.Rd
    the following line:

   \URLtoSource{https://svn.r-project.org/R/% <linebreak>
                branches/R-2-xx-branch/src/library/base/sample.R}

   (OK, yet another markup command to be rendered by the
    new Rd parser...)

   Advantage: Following this link in a browser would then
   also display comments in R source, without the caveats
   mentioned in Uwe's article. Also no need to download and unpack
   all the source tar-ball.

   Disadvantage: Presumably more traffic on svn.r-project.org ...

   I think (1) should be feasible automatically
   (at least to a large extent).

(2) references to C code interfaced to through .Internal() /
    .Primitive() as comments in R code

    Could you think of an automatic way of inserting references
    into the R source containing the call to .Internal() /
    .Primitive() ---

    some (standardized) comment with a link referring to the
    respective C source file, or, even better, to the corresponding
    C function(s), possibly again an URL to the svn repository ?

    Example: code to sample.R

    #  File src/library/base/R/sample.R
    #  Part of the R package, http://www.R-project.org
    #
     --- [snip] ---
    #  http://www.r-project.org/Licenses/

    sample <- function(x, size, replace=FALSE, prob=NULL)
    {
        if(length(x) == 1L && is.numeric(x) && x >= 1) {
	   if(missing(size)) size <- x
   	   .Internal(sample(x, size, replace, prob))
        }
        else {
	   if(missing(size)) size <- length(x)
	   x[.Internal(sample(length(x), size, replace, prob))]
     #
    ###new proposed comment:
     #
     ### C code interfaced to is implemented in
     ###          R_HOME/src/main/random.c
     ###
     ### or: even "nicer"
     ###
     ### corresponding C code may be inspected in
     ###     https://svn.r-project.org/R/branches/% <linebreak>
     ###           R-2-xx-branch/src/main/random.c
     ###
     ### <and, optionally something like>
     ###
     ### as functions ProbSampleReplace(), ProbSampleNoReplace(),
     ###               SampleReplace(),  SampleNoReplace(), .....
     ###               <maybe more>
     #
    ###end.new comment
     #
        }
    }
    --- snip ---

    (The actual list of C functions would not be urgent at all;
     finding the "right" source file already would mean
     the big step)

     As indicated in Uwe's article, one start to automatize this,
     I guess, would be to build up a table with columns
          R function name : R-source file : C-source file
     from the entries in R_HOME/src/main/names.c

These two enhancements would help outsiders very much to spot the
corresponding code (and not the least to learn "from the Giants").

 --- just a "wish for enhancement" though, certainly not of
     top priority.


Any comments are welcome,

Best, Peter