Rationalize `navigateToFile()` and `documentOpen()`

[jennybc]

It feels like navigateToFile() and openDocument() are basically the same, so I'm left wondering which one I should use.

I note that documentOpen() has not yet appeared in a released version of rstudioapi, so this can still be rationalized easily.

From where I sit, it feels like documentOpen() should be a straight call to .rs.api.documentOpen(filePath, line = line, col = col, moveCursor = moveCursor). The current call to normalizePath(path, winslash = "/", mustWork = TRUE) in this package seems unnecessary given the argument checking and processing inside .rs.api.documentOpen().

And then maybe navigateToFile() becomes just an alias for documentOpen()? documentOpen() feels like a better name for this operation and fits well into the family of documentVERB() functions.

(.rs.addApiFunction("navigateToFile") is just an alias for .rs.api.documentOpen() at this point.)

---

rstudioapi/R/document-api.R

Lines 246 to 254 in 75e7f6e

	documentOpen <- function(
	path,
	line = -1L,
	col = -1L,
	moveCursor = TRUE)
	{
	path <- normalizePath(path, winslash = "/", mustWork = TRUE)
	callFun("documentOpen", path, line, col, moveCursor)
	}

rstudioapi/R/stubs.R

Lines 238 to 248 in 942cebe

	navigateToFile <- function(file = character(0),
	line = -1L,
	column = -1L,
	moveCursor = TRUE)
	{
	callFun("navigateToFile",
	file,
	as.integer(line),
	as.integer(column),
	as.logical(moveCursor))
	}

https://github.com/rstudio/rstudio/blob/91cb63802260d5489b024538b7e04320615b3dfa/src/cpp/r/R/Api.R#L265-L271

https://github.com/rstudio/rstudio/blob/91cb63802260d5489b024538b7e04320615b3dfa/src/cpp/r/R/Api.R#L652-L706

[kevinushey]

For some historical context, navigateToFile() came first, but had an unfortunate issue -- it (like many other APIs) was not synchronous, and so using it programmatically was challenging. The various document*() APIs are an attempt to rectify this while also being more consistent in naming + scope; however, they do require newer versions of the RStudio IDE.

The main advantage of navigateToFile() is that it'll work with older versions of the IDE. It looks like I unfortunately didn't document where .rs.api.documentOpen() was introduced; I'll take a look at that.

The current call to normalizePath(path, winslash = "/", mustWork = TRUE) in this package seems unnecessary given the argument checking and processing inside .rs.api.documentOpen().

I think you're right. For what it's worth, in some cases, we might perform work in rstudioapi to work around issues in the API interface exposed by RStudio, since updates to rstudioapi are generally much easier than RStudio.

[jennybc]

The main advantage of navigateToFile() is that it'll work with older versions of the IDE.

Yeah I did not even attempt a careful analysis of how rstudioapi behaves against different versions of the IDE. Is that systematically tested in any way or more of a human-curated matter/