remind: Insert, extract, and print "reminders" for functions and...

In remindR: Insert and Extract "Reminders" from Function Comments

Description

Insert, extract, and print text (i.e. character vector) "reminders" either as the "comment" attribute of objects or as delimited comments within function source code.

Usage

remind(x, ...)

## Default S3 method:
remind(x, ...)

## S3 method for class 'function'
remind(x, begin = "<<", end = ">>", ...)

remind(x) <- value

## S3 method for class 'reminder'
print(x, ...)

Arguments

x	An R object/function for remind; a class "reminder" object for print
...	Additional arguments to methods
begin	Character string delimiting reminder beginning
end	Character string delimiting reminder ending
value	Character vector of text to attach as 'comment' attribute

Details

Extracts text between the 'begin' and 'end' delimiting character strings within source code comments. This is mostly intended to enable easy addition and retrieval of informal text notes during the course of script/function development, aka 'reminders', e.g. to fix something, add a validity check, note additional argument requirements etc. Multiple such separately delimited reminders can be included.

As a slight convenience, the function wraps R's existing comment function to attach and extract reminders as the 'comment' attribute of any R object. These can be used to provide information (provenance, context) on objects and even serve as a kind of minimal informal Help documentation for functions, i.e. a sort of simple manual "tooltip" functionality.

Value

A list of S3 class "reminder".

Note

Because there is no fixed syntax in source code comments, extracting reminders cannot be guaranteed to always work correctly. Some simple checks have been included to warn when they may not be properly extracted, but this may not succeed in all cases.

Also, retrieving reminders from functions depends on whether options(keep.source = TRUE) is in use when they are saved.

See Also

comment

Examples

x <- 1:3
remind(x)
remind(x) <- c("first comment","and a second")
remind(x)
remind(x) <- NULL ## removes reminder
remind(x)
f <- function(x){
   y <- x
   ## Some miscellaneous comments
   ## Now <<This is reminder 1>> and next
   ## This is
   ## yet another <<reminder 2 is this>>
   ## some more stuff
   y
}
f(5)
remind(f)
remind(f)<- "something else"
remind(f)
## "tooltip" type example:
my.summary<- function(x, fun = mean,...)fun(x)
remind(my.summary)<-
"Don't forget to include the na.rm argument if missing values might be present"
remind(my.summary)
rm(f,x,my.summary)

Example output

No reminders

[1] first comment
 
[2] and a second
 
No reminders

[1] 5
No reminders

In function:
No reminders

In comment:
[1] something else
 
In function:
No reminders

In comment:
[1] Don't forget to include the na.rm argument if missing values might be
 present
 

remindR documentation built on May 2, 2019, 8:54 a.m.