[Roxygen-devel] [roxygen2] roxygenise, setGeneric and .svn directory

[Renaud Gaujoux]

Hi,

I removed all the "isGeneric" tests and things work fine. I think I took 
the habit to put these (long ago) because it was giving me errors when 
directly sourcing the code when still developing packages. Maybe 
setGeneric do this by itself now, which I am happy to realise.

I was not roxigenising in place because I had some manually made Rd 
files in the man directory, and didn't want to overwrite them.
I am doing things in place now, and it works great. Will try to create a 
simple reproducible example of the errors.
I think a simple SVN controlled package root directory + roxigenise('.', 
'../testtoxygen') should be enough.
SVN directories are generally read-only, which is what must be causing 
of the warnings.

A side suggestion:
I think embedded documentation is fantastic and is the way to go for 
efficient programming, so everything that can be done automatically for 
the developer should be done.
For example, when using the tag rdname to merge documentation for 
related functions, all the tags are currently concatenated one after the 
other (description, details, return value, parameters, etc..). It would 
be nice to really merge them and automatically add separators that give 
the relevant method/function name, when necessary. This would be useful 
espcially for the @param tag that is otherwise likely to produce 
duplicated entries. But it will also be very useful when documenting S4 
methods, so that one does not need to repeat the name of the method in 
the documentation text, and would make easier later splitting of Rd 
files into separate ones.
I think doing this for all sections would make more structured and 
easier to create merged Rd files.

Thank you.

Renaud

Example:

#' Doing some stuff
#'
#' This function does THIS
#'
#' @param x a matrix
#' @param y a vector
#' @rdname rdfile
funA <- function(x, y){
}

#' This function does THAT
#' @param y a logical
#' @param ... extra parameters passed to plot
#' @rdname rdfile
funB <- function(x, y, ...){
}

would generate the following rdfile.Rd

\title{Doing Some Stuff}
\description{

\code{funA} This function does THIS

\code{funB} This function does THAT

\usage{
funA(x, y, ...)
funB(x, y, ...)
}

\parameters{

\item{x}{ a matrix }
\item{y}{
     For \code{funA}: a vector
     For \code{funB}: a logical
}
\item{...}{extra parameters passed to plot}

}

}

-- 
Renaud Gaujoux
Computational Biology - University of Cape Town
South Africa


On 15/08/2011 11:43, Hadley Wickham wrote:
>> - If I run twice in a row roxygenise, I get error(s) about undefined
>> definition for S4 generic functions.
>> I guess it is an issue of where the generic are looked for.
>> I always define generic as follows:
>>
>> if ( !isGeneric("myfun") ) setGeneric('myfun', function(x, annotation, ...)
>> standardGeneric('myfun'))
>>
>> as I thought this was the portable way of defining generics. If I remove the
>> test for the existence of the generic there are no more errors. Is this test
>> actually not required or even not recommend?
> Hmmm, I don't think you're supposed to do this - namespaces should
> take care of potential conflicts between generics in different
> packages.
>
>> - I get lots of warnings linked to permission issues in the .svn
>> subdirectories that are copied with the package root directory, e.g.:
>>
>> In file.create(to[okay]) :
>>    cannot create file '../testroxy/.svn/text-base/NAMESPACE.svn-base', reason
>> 'Permission denied'
>>
>> I like the fact the .svn directory are actually copied, as it allows me to
>> check for modifications made by roxygenise on the Rd, NAMESPACE or
>> DESCRIPTION files. Any way to avoid these warnings?
> Hard to know why you're getting these errors without a reproducible
> example?  Is the a reason you're not roxygenising in place?
>
> Hadley
>

 

###
UNIVERSITY OF CAPE TOWN 

This e-mail is subject to the UCT ICT policies and e-mail disclaimer published on our website at http://www.uct.ac.za/about/policies/emaildisclaimer/ or obtainable from +27 21 650 9111. This e-mail is intended only for the person(s) to whom it is addressed. If the e-mail has reached you in error, please notify the author. If you are not the intended recipient of the e-mail you may not use, disclose, copy, redirect or print the content. If this e-mail is not related to the business of UCT it is sent by the sender in the sender's individual capacity.

###