hadley wickham wrote: > One of the recurring themes in the recent UserR conference was that > many people find it difficult to find the functions they need for a > particular task. Sandy Weisberg suggested a small idea he would like > to see: a hints function that given an object, lists likely > operations. I've done my best to implement this function using the > tools currently available in R, and my code is included at the bottom > of this email (I hope that I haven't just duplicated something already > present in R). I think Sandy's idea is genuinely useful, even in the > limited form provided by my implementation, and I have already > discovered a few useful functions that I was unaware of. > > While developing and testing this function, I ran into a few problems > which, I think, represent underlying problems with the current > documentation system. These are typified by the results of running > hints on a object produced by glm (having class c("glm", "lm")). I > have outlined (very tersely) some possible solutions. Please note > that while these solutions are largely technological, the problem is > at heart sociological: writing documentation is no easier (and perhaps > much harder) than writing a scientific publication, but the rewards > are fewer. > > Problems: > > * Many functions share the same description (eg. head, tail). > Solution: each rdoc file should only describe one method. Problem: > Writing rdoc files is tedious, there is a lot of information > duplicated between the code and the documenation (eg. the usage > statement) and some functions share a lot of similar information. > Solution: make it easier to write documentation (eg. documentation > inline with code), and easier to include certain common descriptions > in multiple methods (eg. new include command) > > * It is difficult to tell which functions are commonly > used/important. Solution: break down by keywords. Problem: keywords > are not useful at the moment. Solution: make better list of keywords > available and encourage people to use it. Problem: people won't > unless there is a strong incentive, plus good keywording requires > considerable expertise (especially in bulding up list). This is > probably insoluable unless one person systematically keywords all of > the base packages. > > * Some functions aren't documented (eg. simulate.lm, formula.glm) - > typically, these are methods where the documentation is in the > generic. Solution: these methods should all be aliased to the generic > (by default?), and R CMD check should be amended to check for this > situation. You could also argue that this is a deficiency with my > function, and easily fixed by automatically referring to the generic > if the specific isn't documented. > > * It can't supply suggestions when there isn't an explicit method > (ie. .default is used), this makes it pretty useless for basic > vectors. This may not really be a problem, as all possible operations > are probably too numerous to list. > > * Provides full name for function, when best practice is to use > generic part only when calling function. However, getting precise > documentation may requires that full name. I do the best I can > (returning the generic if specific is alias to a documentation file > with the same method name), but this reflects a deeper problem that > the name you should use when calling a function may be different to > the name you use to get documentation. > > * Can only display methods from currently loaded packages. This is a > shortcoming of the methods function, but I suspect it is difficult to > find S3 methods without loading a package. > > Relatively trivial problems: > > * Needs wide display to be effective. Could be dealt with by > breaking description in a sensible manner (there may already by R code > to do this. Please let me know if you know of any) > > * Doesn't currently include S4 methods. Solution: add some more code > to wrap showMethods > > * Personally, I think sentence case is more aesthetically pleasing > (and more flexible) than title case. > > > Hadley > > > hints <- function(x) { > db <- eval(utils:::.hsearch_db()) > if (is.null(db)) { > help.search("abcd!", rebuild=TRUE, agrep=FALSE) > db <- eval(utils:::.hsearch_db()) > } > > base <- db$Base > alias <- db$Aliases > key <- db$Keywords > > m <- all.methods(class=class(x)) > m_id <- alias[match(m, alias[,1]), 2] > keywords <- lapply(m_id, function(id) key[key[,2] %in% id, 1]) > > f.names <- cbind(m, base[match(m_id, base[,3]), 4]) > f.names <- unlist(lapply(1:nrow(f.names), function(i) { > if (is.na(f.names[i, 2])) return(f.names[i, 1]) > a <- methodsplit(f.names[i, 1]) > b <- methodsplit(f.names[i, 2]) > > if (a[1] == b[1]) f.names[i, 2] else f.names[i, 1] > })) > > hints <- cbind(f.names, base[match(m_id, base[,3]), 5]) > hints <- hints[order(tolower(hints[,1])),] > hints <- rbind( c("--------", "---------------"), hints) > rownames(hints) <- rep("", nrow(hints)) > colnames(hints) <- c("Function", "Task") > hints[is.na(hints)] <- "(Unknown)" > > class(hints) <- "hints" > hints > } > > print.hints <- function(x, ...) print(unclass(x), quote=FALSE) > > all.methods <- function(classes) { > methods <- do.call(rbind,lapply(classes, function(x) { > m <- methods(class=x) > t(sapply(as.vector(m), methodsplit)) #m[attr(m, "info")$visible] > })) > rownames(methods[!duplicated(methods[,1]),]) > } > > methodsplit <- function(m) { > parts <- strsplit(m, "\\.")[[1]] > if (length(parts) == 1) { > c(name=m, class="") > } else{ > c(name=paste(parts[-length(parts)], collapse="."), > class=parts[length(parts)]) > } > } > > ______________________________________________ > R-help@stat.math.ethz.ch mailing list > https://stat.ethz.ch/mailman/listinfo/r-help > PLEASE do read the posting guide! http://www.R-project.org/posting-guide.html
just a feedback: that's a useful function, thank you. but the problem is probably more general: frequently I do not really want to know what I generally can do with a data frame, for instance, but rather I would like to use `help.search' as I would use, say, Google (and with the same rate of success...). but the actual `keywords' in the manpages seem insufficient and `help.search' does not allow full text search in the manpages (I can imagine why (1000 hits...), but without such a thing google, for instance, would probably not be half as useful as it is, right?) and there is no "sorting by relevance" in the `help.search' output, I think. how this sorting could be achieved is a different question, of course. ______________________________________________ R-help@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide! http://www.R-project.org/posting-guide.html