| Title: | Enhanced Help to Enable "Docstring"-Comments in Users Functions |
| Version: | 1.2.1 |
| Author: | Marcelo Ponce [aut, cre] |
| Maintainer: | Marcelo Ponce <m.ponce@utoronto.ca> |
| Description: | By overloading the R help() function, this package allows users to use "docstring" style comments within their own defined functions. The package also provides additional functions to mimic the R basic example() function and the prototyping of packages. |
| URL: | https://github.com/mponce0/eHelp |
| BugReports: | https://github.com/mponce0/eHelp/issues |
| License: | GPL-2 | GPL-3 [expanded from: GPL (≥ 2)] |
| Encoding: | UTF-8 |
| RoxygenNote: | 7.1.0 |
| Suggests: | testthat (≥ 2.1.0), knitr, rmarkdown, crayon |
| VignetteBuilder: | knitr |
| NeedsCompilation: | no |
| Packaged: | 2023-01-06 19:46:49 UTC; marcelo |
| Repository: | CRAN |
| Date/Publication: | 2023-01-06 23:30:09 UTC |
function that allows to execute the examples from user defined functions
Description
function that allows to execute the examples from user defined functions
Usage
eexample(..., skip.donts = FALSE)
Arguments
... |
function name of a user defined fn |
skip.donts |
boolean argument to specify whether dontest or dontrun examples should be skiped or not |
Enhanced-Help Function: ehelp() This function displays docstring style comments used as help liners for user defined functions.
Description
Enhanced-Help Function: ehelp() This function displays docstring style comments used as help liners for user defined functions.
Usage
ehelp(
fun,
fn.name = as.character(substitute(fun)),
coloring = FALSE,
output = "none"
)
Arguments
fun |
function name of an user-defined function |
coloring |
a Boolean flag indicating whether to use colors for displaying messages |
output |
specify if the documentation generated by the ehelp() will be saved in a file, possible values are "txt" (for help only), "TXT" (for help and full fn body) or "none" (default, for in screen display only) |
fn |
name of the function (string) |
Examples
myTestFn <- function(x,y,z,t=0) {
#'
#' This is just an example of a dummy fn
#'
#'
#' @email myemail@somewhere.org
#' @author author
#
#
#' @demo
#' @examples myTestFn(x0,y0,z0)
}
ehelp(myTestFn)
## this requires the "crayon" package to work
ehelp(myTestFn, coloring=TRUE)
## generation of documentation for a fn in different formats
## by indicating a particular format, ehelp will save in a file
## the corresponding documentation of the selected fn
## Valid formats are:
## txt (plain-text), ascii (text with ESC-codes for coloring),
## latex, html, markdown
## Additionally, capitalized versions of these formats, will also include
## the listing of the fn
## Not run:
ehelp(myTestFn, output="latex")
ehelp(myTestFn, output="TXT")
ehelp(myTestFn, coloring=TRUE, output="HTML")
ehelp(myTestFn, coloring=TRUE, output="ASCII")
ehelp(myTestFn, coloring=TRUE, output="markdown")
## End(Not run)
This function defines the "palettes" of colours to be used by eHelp() There are two options right now: "color" and "bw"; default is set to "color"
Description
This function defines the "palettes" of colours to be used by eHelp() There are two options right now: "color" and "bw"; default is set to "color"
Usage
ehelp.palette(palette = "color")
Arguments
palette |
allows to select which color palette to use |
Function to define specifics structures, symbols and 'codes'
Description
Function to define specifics structures, symbols and 'codes'
Usage
## S3 method for class 'defns'
format(fmt, filename = "", ending = NA)
Arguments
fmt |
an specific file format; possible values are: txt, html, latex, markdown |
ending |
optional argument for selecting when continuing saving into the file |
Wrapper Help Function
Description
This function is a wrapper around the R's system help() function. It allows the user to include docstring styles documentation and displayed it as help or information to the users using the help() command.
Usage
help(
topic,
package = NULL,
lib.loc = NULL,
verbose = getOption("verbose"),
try.all.packages = getOption("help.try.all.packages"),
help_type = getOption("help_type")
)
Arguments
topic |
topic/or/function name to search for |
package |
package where to search |
lib.loc |
location of R libraries |
verbose |
for diplaying the filename |
try.all.packages |
attempt to go trough all installed packages |
help_type |
format of the displayed help (text,html, or pdf) |
Details
Parameters are the same as in utils::help, see help(help,package='utils') for further details.
Examples
compute3Dveloc <- function(x,y,z,t){
#' @fnName compute3Dveloc
#' this function computes the velocity of an object in a 3D space
#' @param x vector of positions in the x-axis
#' @param y vector of positions in the y-axis
#' @param z vector of positions in the z-axis
#' @param t time vector corresponding to the position vector
# number of elements in vectors
n <- length(t)
# compute delta_t
delta_t <- t[2:n]-t[1:n-1]
# compute delta_x
delta_x <- x[2:n]-x[1:n-1]
# compute delta_y
delta_y <- y[2:n]-y[1:n-1]
# compute delta_z
delta_z <- z[2:n]-z[1:n-1]
# do actual computation of velocity...
veloc3D <- list(delta_x/delta_t, delta_y/delta_t, delta_z/delta_t)
# return value
return(veloc3D)
}
help(compute3Dveloc)
method associated with ehelp objects
Description
method associated with ehelp objects
Usage
print(ehelp.obj)
Arguments
ehelp.obj |
ehelp object |
function associated to the ehelp object method
Description
function associated to the ehelp object method
Usage
## S3 method for class 'ehelp'
print(ehelp.obj, coloring = T)
Arguments
ehelp.obj |
ehelp object |
coloring |
whether to use colors or not when displaying the help |
function to process the type output requested
Description
function to process the type output requested
Usage
processOutput(ehelp.obj, fnName, fnCorpus, output)
Arguments
ehelp.obj |
ehelp object generated by the ehelp() fn |
fnName |
name of the function |
fnCorpus |
function definition |
output |
type of output, valid options are "txt", "TXT", "html", "HTML", "latex", "LATEX", "markdown", "MARKDOWN" |
function that allows to load the functions from a package in preparation for CRAN, as if it is being loaded by loading all the fns defined in the R sub-directory of the package, ie. "myPckg/R"
Description
function that allows to load the functions from a package in preparation for CRAN, as if it is being loaded by loading all the fns defined in the R sub-directory of the package, ie. "myPckg/R"
Usage
simulatePackage(pkgLocation = NULL)
Arguments
pkgLocation |
path to the base loaction of the package, under which is expected to found the R sub-directory |
Function to write into a file the listing of the fn.
Description
Function to write into a file the listing of the fn.
Usage
write.Fncorpus(
fnName,
fnListing,
filename,
lines = paste0("/* ################################################ */"),
begining = "",
ending = "",
EoL = "\r\n"
)
Arguments
fnName |
name of the function |
fnListing |
listing of fn to write to file |
filename |
name of the file where to write the documentation |
lines |
optional argument to specify the separation lines to be used |
begining |
an optional argument to specify the initial lines of HTML code |
ending |
an optional argument to specify the last lines of HTML code |
EoL |
optional argument to specify the EOL (if need, eg. for html) |
function for including informaton about time and date in the generated files
Description
function for including informaton about time and date in the generated files
Usage
write.Info(
filename,
lines = paste0("-----------------------------------------------"),
pre = "",
post = "",
EoL = ""
)
Arguments
filename |
name of the file where to write the documentation |
lines |
optional argument to specify the separation lines to be used |
post |
optional argument to specify post-information code to be added (if need, eg. for html) |
EoL |
optional argument to specify the EOL (if need, eg. for html) |
function for writing ehelp output to a local text file
Description
function for writing ehelp output to a local text file
Usage
write.ehelp(X.obj, filename)
Arguments
X.obj |
ehelp object |
filename |
name of the file where to write the documentation |
function for writing ehelp output to a local LaTeX file
Description
function for writing ehelp output to a local LaTeX file
Usage
write.fmt(X.obj, format, filename, leaveOpen = FALSE)
Arguments
X.obj |
ehelp object |
format |
type of output: txt, latex, html |
filename |
name of the file where to write the documentation |
leaveOpen |
boolean argument to leave the file open |