{"Package":"ehelp","Title":"Enhanced Help to Enable \"Docstring\"-Comments in Users Functions","Version":"1.1.1","Authors@R":"\nperson(given = \"Marcelo\",\nfamily = \"Ponce\",\nrole = c(\"aut\", \"cre\"),\nemail = \"mponce@scinet.utoronto.ca\")","Author":"Marcelo Ponce [aut, cre]","Maintainer":"Marcelo Ponce ","Description":"By overloading the R help() function, this package allows users to use \"docstring\" style comments within their own defined functions.","URL":"https://github.com/mponce0/eHelp","BugReports":"https://github.com/mponce0/eHelp/issues","License":"GPL (>= 2)","Encoding":"UTF-8","LazyData":"true","RoxygenNote":"6.1.99.9001","Suggests":"testthat (>= 2.1.0), knitr, rmarkdown, crayon","VignetteBuilder":"knitr","NeedsCompilation":"no","Packaged":"2019-12-13 14:52:41 UTC; mjponce","Repository":"CRAN","Date/Publication":"2019-12-13 15:30:02 UTC","repoType":"cran","tarballUrl":"ftp://cran.r-project.org/pub/R/src/contrib/ehelp_1.1.1.tar.gz","jsonAuthors":[{"name":"Marcelo Ponce","email":"mponce@scinet.utoronto.ca","maintainer":true}],"readme":"# eHelp\n\n\n\n## Introduction\nThe \"eHelp\" (enhnaced-Help) package allows users to include \"a-la-docstring\" comments in their own functions and utilize the help() function to automatically provide documentation within an R session.\n\nInspired by Python's a-la-docstring comments and the existant \"docstring\" R package [1], the package \"eHelp\" attempts to offer similar functionalities by allowing comments \"a-la-docstring\" style to be displayed as help in user-defined functions.\n\n### Rationale\nDocumenting code is among the \"best practices\" followed when developing code in a professional manner, and even when guided generation of documentation is possible while developing R packages, we still belive that offering users a tool that allows them to document their functions via docstring comments is useful.\n\nMoreover it can be used for instructing and teaching best practices while training coders that are just starting.\nOr, in this case the eHelp package could help package developer while prototyping their own packages, as eHelp will allow them to explore how the the help of the functions defined within their package will look like and even save this documentation in files of different formats.\n\nThe inclusion of \"docstring\" comments are an useful and easy way of allowing programmers to include comments and at the same time document their codes.\nUnfortunately such functionality is not present in the R core and basic features for user-defined functions.\n\nThe main reason why we decided to create this package is because we noticed several issues with the already available in R \"docstring\" package:\n* we have noticed that the 'docstring' package does not work with more than one function defined within a script\n* sometimes the documentation is not updated even when the function is reloaded (ie. Windows OS)\n* the package hasn't been updated or mantained since its creation in 2017 [2]\n* we prefered to overload the \"help()\" function instead of the \"?\" one, which we find more frequently used\n* another advantage of using the \"help()\" function, is that tab-completion works and we have overload the function so that it cascades down to the R utils::help() function when the user-defined function is not present in the working environment.\n\n### Features\nThe \"eHelp\" package attempts to provide documentation for user-defined functions based on decorated \"a-la-docstring\" comments included in the function's definition.\nIt does this by employing a really \"simple\" approach in the sense that it does not attempt to generate roxygen based documentation for the user-defined functions, but instead it just displays the information decorated with _#'_ directly into the console.\nThis, we belive, in this particular case represents an advantage, specially considering that the package is aimed to provide help for user-defined functions. For instance, one of the reported issues with the \"docstring\" package is that the documentation generated wasn't updated after the user-definitions were updated and re-sourced. \n\nComments with docstrings should be included within the function definition, as eHelp will look into the body of the function for this type of comments.\n\nAn additional feature of the \"eHelp\" package is that it will automatically generate an \"usage\" report, independently of whether the user specified it on the docstring-ed comments utilizing the \"@usage\" keyword. It does this, by inspecting the function's definition and parsing an expression with the function's name and list of arguments.\n\nThe following keywords can be used to decorate and provide details as comments in user-defined functions:\n\n```\n@fnName : provides the name of the function\n@param : list the arguments and its description of the arguments expected by the function\n@descr : general description of the function\n@return : description of what the function returns\n@usage : how the function is called\n@author : name of the author(s) of the function\n@email : contact information of the author(s)\n@repo : repository where to get the function from\n@ref : any suitable reference needed\n```\n\nFurther keywords can be added on-demand, please contact the developer if you would like to add other keywords to the list.\n\nSome keywords are explicited ignored, such as: \"@keyword internal\", \"@importFrom\", \"@export\"; as these won't contribute much to the usage of the user-defined functions.\n\n### Highlighting\nWe have included extended functionalities to the \"ehelp()\" function, which allows the user to display the information about the requested function using highlighting features.\nFor such functionalities to work you will have to use\n ```ehelp(Name.of.Function, coloring=TRUE)```\nthis requires that the \"crayon\" package [3] is available (installed) in the system.\n\n\n### Saving the documentation of the functions to file in different formats\nAnother additional feature of the ehelp() function, is that it can be\ninstructed to create a file with the content of the help for a given function\nin file utilizing an specific file format for the output.\nThis is achived by indicating the argument ```output``` and one of the\nfollowing values:\n\noutput\t | file format\n------\t | -----------\ntxt\t | plain text\nascii\t | similar to plain txt but including ESCape codes like the ones used for coloring the output in the R session\nhtml\t | HTML format, the user can open the output with any web browser\nlatex\t | LaTeX format\nmarkdown | Markdown format\n---------------------------\n\nWhen this option is used, the output generated will be saved in the current\nworking directory in a file named employing the following convention:\n\n\tNameOfTheFunction-eHelp.FMT\n\nwhere ```NameOfTheFunction``` is the name of the function and ```FMT``` is the\ncorrespodning extension format selected.\n\nCapitalized options are also available and when used, not only the help associated\nwith the function is saved in the file but also the actual listing of the\nfunction too.\n\n\n\n## Installation\n\nFor using the \"eHelp\" package, first you will need to install it.\n\nThes table version can be downloaded from the CRAN repository:\n```\ninstall.packages(\"ehelp\")\n```\n\nTo obtain the development version you can get it from the github repository, i.e.\n```\n# need devtools for installing from the github repo\ninstall.packages(\"devtools\")\n\n# install eHelp\ndevtools::install_github(\"mponce0/eHelp\")\n\n# load eHelp\nlibrary(eHelp)\n```\n\n## How does it work?\nAfter loading the \"eHelp\" package, the function help() from the R system will be overloaded (\"masked\") by a wrapper function that allows us to redirect the calls to the help() function either to our eHelp() function or to the R's core help() one.\nWhen the wrapper function detects that help is being invoqued in an user-defined function, then it offload the call to our own eHelp() function. The eHelp() function will parse the content of the inquired function looking for comments decorated with #' and parse them depending on their content. In particular, it will take special care of the comments including any of the keywords described above and the usage of the function.\n\n\n## Examples\nAll what is needed for eHelp to offer help in your own defined functions is to add comments including \" #' \" and its respective keywords.\nWe offer below some examples, just recall to load the eHelp package before using help() with your own functions.\n\n```\ncompute3Dveloc <- function(x,y,z,t){\n#' @fnName compute3Dveloc\n#' this function computes the velocity of an object in a 3D space\n#' @param x vector of positions in the x-axis\n#' @param y vector of positions in the y-axis\n#' @param z vector of positions in the z-axis\n#' @param t time vector corresponding to the position vector\n\n # number of elements in vectors\n n <- length(t)\n # compute delta_t\n delta_t <- t[2:n]-t[1:n-1]\n # compute delta_x\n delta_x <- x[2:n]-x[1:n-1]\n # compute delta_y\n delta_y <- y[2:n]-y[1:n-1]\n # compute delta_z\n delta_z <- z[2:n]-z[1:n-1]\n # do actual computation of velocity...\n veloc3D <- list(delta_x/delta_t, delta_y/delta_t, delta_z/delta_t)\n # return value\n return(veloc3D)\n}\n```\n\n```\n> help(compute3Dveloc)\nFunction Name:\t compute3Dveloc\n this function computes the velocity of an object in a 3D space \nArguments: \n\t x vector of positions in the x-axis \n\t y vector of positions in the y-axis \n\t z vector of positions in the z-axis \n\t t time vector corresponding to the position vector \n\n### Usage:\n compute3Dveloc(x, y, z, t)\n```\n\n\nEven when the @fnName and @params are not definied, the usage will be generated based on the actual function definition:\n```\nmyTestFn <- function(x,y,z,t=0) {\n#'\n#' This is just an example of a dummy fn\n#'\n#'\n#' @email myemail@somewhere.org\n#' @author author\n#\n#\n#' @demo\n#' @example myTestFn(x0,y0,z0)\n}\n```\n```\n> help(myTestFn)\nFunction Name:\t myTestFn \n\n This is just an example of a dummy fn \n \n \nContact:\t myemail@somewhere.org \nAuthor:\t author\n @demo \n\n### Examples: \n\t myTestFn(x0,y0,z0) \n\n### Usage: \n\t myTestFn(x, y, z, t = 0) \n```\n\n\n\nIt is also possible to invoque the \"ehelp()\" function directly, and in that way further options are available:\n```\n> ehelp(myTestFn, coloring=TRUE)\n__Function Name:__\t myTestFn \n\n This is just an example of a dummy fn \n \n \n__Contact:__\t myemail@somewhere.org \n__Author:__\t author\n @demo \n\n### Examples:\n\t myTestFn(x0,y0,z0) \n\n__### Usage:__\n\t myTestFn(x, y, z, t = 0)\n```\n\n\nAdditionaly is possible to use ehelp() for saving of documentation of a\nfunction into a file with an specific file format, this is acieved by specifying the ```output``` argument in ehelp().\nAvailable formats are:\ntxt (plain-text), ascii (text with ESC-codes for coloring), latex, html, and markdown.\nAdditionally, capitalized versions of these formats, will also include\nthe listing of the function, eg.\n\n```\nehelp(myTestFn, output=\"latex\")\n```\n**myTestFn-eHelp.tex written to CURRENT_DIR**\n...\n\n```\nehelp(myTestFn, output=\"TXT\")\n\nehelp(myTestFn, coloring=TRUE, output=\"HTML\")\n\nehelp(myTestFn, coloring=TRUE, output=\"ASCII\")\n\nehelp(myTestFn, coloring=TRUE, output=\"markdown\")\n```\n\n\n### References\n[1] https://cran.r-project.org/package=docstring\n\n[2] https://github.com/dasonk/docstring\n\n[3] https://github.com/r-lib/crayon","jobInfo":{"package":"ehelp","version":"1.1.1","parsingStatus":"success","parserVersion":1,"parsedAt":"2020-04-05T07:30:19+0000"}}