Merge pull request #397 from krlmlr/inline-rox

Allow roxygen comments in object to be documented

NEWS.md

@@ -6,6 +6,11 @@
   output. `@rawNamespace` allows you to insert literal text in your namespace:
   this can be useful for conditional imports (#385). 
 
+* The contents of documented functions are now also parsed for tags. This allows,
+  e.g., documenting a parameter's type close to where this type is checked,
+  or documenting implementation details close to the source, and simplifies
+  future extensions such as the documentation of R6 classes (#397, @krlmlr).
+
 * `register.preref.parser()` and `register.preref.parsers()`  have been 
   deprecated - please use `register_tags()` instead.
 

R/parse.R

@@ -46,8 +46,8 @@ comments <- function(refs) {
   # first_line, first_byte, last_line, last_byte
   com <- vector("list", length(refs))
   for(i in seq_along(refs)) {
-    # Comments begin after last line of last block, and continue to
-    # first line of this block
+    # Comments begin after last line of last block, and this block is included
+    # so that it can be parsed for additional comments
     if (i == 1) {
       first_byte <- 1
       first_line <- 1
@@ -56,17 +56,8 @@ comments <- function(refs) {
       first_line <- refs[[i - 1]][3]
     }
 
-    last_line <- refs[[i]][1]
-    last_byte <- refs[[i]][2] - 1
-    if (last_byte == 0) {
-      if (last_line == 1) {
-        last_byte <- 1
-        last_line <- 1
-      } else {
-        last_line <- last_line - 1
-        last_byte <- 1e3
-      }
-    }
+    last_line <- refs[[i]][3]
+    last_byte <- refs[[i]][4]
 
     lloc <- c(first_line, first_byte, last_line, last_byte)
     com[[i]] <- srcref(srcfile, lloc)

tests/testthat/test-inline.R

@@ -0,0 +1,34 @@
+context("Inline")
+roc <- rd_roclet()
+
+test_that("Inline comments are supported", {
+  out <- roc_proc_text(roc, "
+    #' Description
+    a <- function(x) {
+      #' @param x an integer
+      stopifnot(is.integer(x))
+    }")[[1]]
+  expect_equal(get_tag(out, "param")$values, c(x="an integer"))
+})
+
+test_that("Inline comments just before the closing brace are allowed", {
+  out <- roc_proc_text(roc, "
+    #' Description
+    a <- function(x) {
+      #' @param x an integer
+      stopifnot(is.integer(x))
+
+      #' @seealso somewhere
+    }")[[1]]
+  expect_equal(get_tag(out, "seealso")$value, "somewhere")
+})
+
+test_that("Inline comments do not extend past the closing brace", {
+  out <- roc_proc_text(roc, "
+    #' Description
+    a <- function(x) {
+      #' @param x an integer
+      stopifnot(is.integer(x))
+    }; #' @seealso somewhere")[[1]]
+  expect_null(get_tag(out, "seealso"))
+})