{"id":17154084,"url":"https://github.com/mponce0/ehelp","last_synced_at":"2025-08-11T21:45:54.718Z","repository":{"id":56936420,"uuid":"211543277","full_name":"mponce0/eHelp","owner":"mponce0","description":"repo for the eHelp package","archived":false,"fork":false,"pushed_at":"2023-01-06T15:33:26.000Z","size":338,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-02T03:52:06.184Z","etag":null,"topics":["ala-docstring","best-practices","developer-tools","docstring","docstring-comments","documentation","prototyping","r"],"latest_commit_sha":null,"homepage":null,"language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mponce0.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-09-28T18:16:28.000Z","updated_at":"2023-01-05T05:16:59.000Z","dependencies_parsed_at":"2023-02-06T06:01:55.624Z","dependency_job_id":null,"html_url":"https://github.com/mponce0/eHelp","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mponce0%2FeHelp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mponce0%2FeHelp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mponce0%2FeHelp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mponce0%2FeHelp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mponce0","download_url":"https://codeload.github.com/mponce0/eHelp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245277016,"owners_count":20589077,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ala-docstring","best-practices","developer-tools","docstring","docstring-comments","documentation","prototyping","r"],"created_at":"2024-10-14T21:48:13.188Z","updated_at":"2025-03-24T13:24:18.619Z","avatar_url":"https://github.com/mponce0.png","language":"R","readme":"# eHelp\n\n\u003c!-- badges: start --\u003e\n[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version-last-release/ehelp)](https://cran.r-project.org/package=ehelp)\n[![cran checks](https://badges.cranchecks.info/worst/ehelp.svg)](https://cran.r-project.org/web/checks/check_results_ehelp.html)\n[![cran checks](https://badges.cranchecks.info/summary/ehelp.svg)](https://cran.r-project.org/web/checks/check_results_ehelp.html)\n[![Downloads last.mnth](https://cranlogs.r-pkg.org/badges/ehelp)](https://cran.r-project.org/package=ehelp)\n\u003c!--[![CRAN checks](https://cranchecks.info/badges/worst/ehelp)](https://cranchecks.info/pkgs/ehelp) --\u003e\n\u003c!-- badges: end --\u003e\n\n## Introduction\nThe \"eHelp\" (enhanced-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 existent \"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\nThe \"eHelp\" package also provides a few more functions aimed to assist\nin the development and prototyping the functions and R package:\n* the function `eexample()`, analog to R's basic `example()` function, allows users to run examples in user-defined functions.\n* the function `simulatePackage()`, will load the functions from an specified directory, mimicking the load of a package which includes the definition of these 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 believe 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 maintained since its creation in 2017 [2]\n* we preferred 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## eHelp Main Functions:\n\nfunction   |  description\n---        |  ---\n`ehelp`    |  main function to provide help based on docstring comments for user-defined functions\n`help`     |  wrapper around R's basic help function, that offloads user-defined functions to the `ehelp()` function\n`eexample` | function that runs examples from user-defined functions\n`simulatePackage` | function that loads R files within a given directory, similar to what the `library()` function would do with an installed package\n---\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 believe, 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@examples :  include examples of how to use user-defined function\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 explicitly 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 achieved 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\ncorresponding 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### Running examples from user-defined functions\nThe eHelp's `eexample()` function will use the `ehelp()` function to determine whether\nthere are examples included in user-defined functions and run them, similarly to what\nR's `example()` functions does for system and/or library ones.\nFor that, the keyword `@examples` should be included in the user-defined comments.\nThe `eexample` function can distinguish between the \"\\donttest{}-\\dontrun{}-\\dontshow{}\"\nindicators.\nBy default the `eexample` function will run all the examples, but an optional argument\n`skip.donts` can be used to skip and avoid running these examples.\n\n\n## Installation\n\nFor using the \"eHelp\" package, first you will need to install it.\n\nThe stable 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\nAfter installing the package, you need to load it, i.e.\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 invoked 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 \u003c- 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 \u003c- length(t)\n   # compute delta_t\n   delta_t \u003c- t[2:n]-t[1:n-1]\n   # compute delta_x\n   delta_x \u003c- x[2:n]-x[1:n-1]\n   # compute delta_y\n   delta_y \u003c- y[2:n]-y[1:n-1]\n   # compute delta_z\n   delta_z \u003c- z[2:n]-z[1:n-1]\n   # do actual computation of velocity...\n   veloc3D \u003c- list(delta_x/delta_t, delta_y/delta_t, delta_z/delta_t)\n   # return value\n   return(veloc3D)\n}\n```\n\n```\n\u003e 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 defined, the usage will be generated based on the actual function definition:\n```\nmyTestFn \u003c- 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#' @examples myTestFn(x0,y0,z0)\n}\n```\n```\n\u003e 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 invoke the \"ehelp()\" function directly, and in that way further options are available:\n```\n\u003e 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\nAdditionally is possible to use ehelp() for saving of documentation of a\nfunction into a file with an specific file format, this is achieved 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\")\nehelp(myTestFn, coloring=TRUE, output=\"HTML\")\nehelp(myTestFn, coloring=TRUE, output=\"ASCII\")\nehelp(myTestFn, coloring=TRUE, output=\"markdown\")\n```\n\n\n### How to Cite this Package\n```R\n\u003e citation(\"ehelp\")\n\nTo cite package ‘ehelp’ in publications use:\n\n  Marcelo Ponce (2019). ehelp: Enhanced Help to Enable\n  \"Docstring\"-Comments in Users Functions. R package version 1.1.1.\n  https://CRAN.R-project.org/package=ehelp\n\nA BibTeX entry for LaTeX users is\n\n  @Manual{,\n    title = {ehelp: Enhanced Help to Enable \"Docstring\"-Comments in Users Functions},\n    author = {Marcelo Ponce},\n    year = {2019},\n    note = {R package version 1.1.1},\n    url = {https://CRAN.R-project.org/package=ehelp},\n  }\n```\n\n\n### Stats\n\u003c!-- badges: start --\u003e\n[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version-last-release/ehelp)](https://cran.r-project.org/package=ehelp)\n[![cran checks](https://badges.cranchecks.info/worst/ehelp.svg)](https://cran.r-project.org/web/checks/check_results_ehelp.html)\n[![cran checks](https://badges.cranchecks.info/summary/ehelp.svg)](https://cran.r-project.org/web/checks/check_results_ehelp.html)\n[![Downloads last.mnth](https://cranlogs.r-pkg.org/badges/ehelp)](https://cran.r-project.org/package=ehelp)\n[![Downloads last.day](https://cranlogs.r-pkg.org/badges/last-week/ehelp)](https://cran.r-project.org/package=ehelp)\n[![Downloads last.day](https://cranlogs.r-pkg.org/badges/last-day/ehelp)](https://cran.r-project.org/package=ehelp)\n\u003c!-- badges: end --\u003e\n\n\u003cp align=\"center\"\u003e\n\t\u003cimg src=\"https://github.com/mponce0/R.pckgs.stats/blob/master/DWNLDS_ehelp.png\" width=\"65%\" alt=\"Download stats\"/\u003e\n\t\u003cfigcaption\u003e\"Live\" download stats, figure generated using \"Visualize.CRAN.Downloads\"\u003c/figcaption\u003e\n\u003c/p\u003e\n\n\u003cobject data=\"https://github.com/mponce0/R.pckgs.stats/blob/master/DWNLDS_ehelp.pdf\" type=\"application/pdf\" width=\"700px\" height=\"700px\"\u003e\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\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmponce0%2Fehelp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmponce0%2Fehelp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmponce0%2Fehelp/lists"}