Refclass and R6 methods should generate aliases

[dmurdoch]

I posted an issue for RSelenium, suggesting that ?findElement should open the ?remoteDriver web page. But really this is a roxygen2 suggestion: when it generates the big help page for the R6 class, it should add aliases for all the methods described in it (and maybe for the fields, too). This would address the problem raised in issue #1039 as well, because a standard Rd link could be used.

It might make sense to also add an alias that included the class name.

That is, in order to find the help for the findElement method, I could do either

?findElement

or

?"remoteDriver$findElement"

(or some other syntax for the last one).

[gaborcsardi]

Yeah, it would be great to have a way to get to the documentation of the methods quicker!

However, one issue with adding the aliases, is R6 methods often have short, concise names, e.g. I couple I have just seen in the wild are label, auth, user, validate, get, set, del, fields, str, etc. Adding aliases automatically for all these method names does not seem like a good idea.

You can always add an alias manually, with @aliases, so the remoteDriver manual page could do that.

I think ideally the help system and the ? shorthand in particular could support R6 and reference classes and open the right manual page for

?remoteDriver$findElement

In HTML help (like RStudio, RGui, etc.) it could even jump to the definition of the method, as roxygen adds HTML anchors already.

[dmurdoch]

Sorry, I made a mistake in posting this question: RSelenium::remoteDriver isn't an R6 class, it's a methods-based reference class. I don't think I can edit the title, but it really should be "Refclass and R6 methods should generate aliases".

Yes, an R solution would be even better. It could do more than roxygen2 could do. For example, by analogy to S4 help support, you could have code where rd is a remoteDriver object, and ?rd$findElement would go to the right place. That doesn't happen now, but it's probably a wishlist item to submit to R.

Regarding the use of short names as method names: the R help system has a way to disambiguate such things when they are in different packages. It currently allows the same alias to be used on multiple help topics in the same package, but doesn't handle them well: it seems to display the first topic it finds, it doesn't bring up the list of all possible matches. So I think you're right, with current R automatically adding a get alias would likely just be confusing.

[gaborcsardi]

Actually, if the help page does not scroll to the right method, then adding an alias to "class$method" is not super helpful, and the same is true for

?class$method

if we patch utils::help() and utils::?, because it will just take you to the same help page as ?class.

[dmurdoch]

I'm thinking of a case where I was looking through some old code that I wrote (looking through someone else's code would be similar). I saw things like

 elem <- rd$findElement(...)

in the code, and wanted to read the docs for findElement. I couldn't easily do ?class because I didn't know the class of rd at that point: to find that, I'd need to run the code up to that point.

[gaborcsardi]

Right, that's a good point. It seems that if we add an alias for class$method, then help.search("method") will find the manual page of the class, so yeah, we should add aliases for class$method.

[mb706]

It might be more beneficial to add method names as \concept instead of as \alias, in cases where different classes have methods of the same name.