{"id":16275613,"url":"https://github.com/dasonk/docstring","last_synced_at":"2025-07-05T03:08:47.132Z","repository":{"id":18546161,"uuid":"84569917","full_name":"Dasonk/docstring","owner":"Dasonk","description":"Provides docstring like functionality to R functions without requiring the need to create a package.","archived":false,"fork":false,"pushed_at":"2021-12-21T22:32:46.000Z","size":472,"stargazers_count":57,"open_issues_count":20,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-06-10T21:01:23.444Z","etag":null,"topics":["devtools","docstring","documentation","documentation-tool","r","r-package","roxygen-style"],"latest_commit_sha":null,"homepage":null,"language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Dasonk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-03-10T14:48:28.000Z","updated_at":"2025-03-22T08:13:26.000Z","dependencies_parsed_at":"2022-08-17T15:31:09.493Z","dependency_job_id":null,"html_url":"https://github.com/Dasonk/docstring","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Dasonk/docstring","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dasonk%2Fdocstring","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dasonk%2Fdocstring/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dasonk%2Fdocstring/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dasonk%2Fdocstring/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Dasonk","download_url":"https://codeload.github.com/Dasonk/docstring/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dasonk%2Fdocstring/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263674377,"owners_count":23494564,"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":["devtools","docstring","documentation","documentation-tool","r","r-package","roxygen-style"],"created_at":"2024-10-10T18:35:33.650Z","updated_at":"2025-07-05T03:08:47.109Z","avatar_url":"https://github.com/Dasonk.png","language":"R","readme":"# docstring\n\n[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version-last-release/docstring)](https://cran.r-project.org/package=docstring) \n[![Build Status](https://travis-ci.org/Dasonk/docstring.svg?branch=master)](https://travis-ci.org/Dasonk/docstring) \n[![Downloads](http://cranlogs.r-pkg.org/badges/docstring)](https://cran.r-project.org/package=docstring)\n\nThe docstring package is an R package that provides the ability to \ndisplay something analagous to\nPython's docstrings within R.  By allowing the user to document\ntheir functions as comments at the beginning of their function\nwithout requiring putting the function into a package we allow\nmore users to easily provide documentation viewable through the native help system within R.\nThe documentation can be viewed either using an accessor function\n(i.e. `docstring(your_function)`) or just like you would for\nany other function (i.e. `?your_function`) and it should\ndisplays just like any other R help files.\n\nThe user will need to be familiar with roxygen style comments (via the [roxygen2 package](https://cran.r-project.org/package=roxygen2))\nto fully utilize the package.  \n\nIdeally this will\nallow users not yet comfortable with package creation to still provide\ndocumentation for their functions. If they use the roxygen style comments when it\nis time to convert their work into a package all they will need to do is move\ntheir pre-existing documentation outside of the function and they will be set.\n\n## Examples\n\n\n```r\nlibrary(docstring)\n\nsquare \u003c- function(x){\n\n    #' Square a number\n    #'\n    #' Calculates the square of the input\n    #'\n    #' @param x the input to be squared\n\n    return(x^2)\n}\n\ndocstring(square)\n# or\n?square\n```\n\n![Square](docs/images/square_web.png)\n\n### R Studio support\n\nIf you are running R through RStudio there is support for displaying the\ndocstring within the RStudio help pane directly.  This is enabled by default. It\nshould detect that you're running RStudio and unless you choose the `rstudio_pane=FALSE`\nwithin `docstring` or set `options(\"docstring_rstudio_help_pane\" = FALSE)` the help\nwill display in the RStudio help pane. If you disable the help pane support then\nthe help will instead display in a web browser.\n\n![Square RStudio](docs/images/square_rstudio.png)\n\nThere is also support for using `?` to access the docstring.  \n\n![Square question](docs/images/square_question.png)\n\n### Single Chunks\n\nOne does not need to adhere completely to the roxygen style for documentation.\nOne notable example is when the docstring is just a single chunk of\ntext with no blank lines or @keywords.  In these cases it is assumed that\nthe text is supposed to be interpreted as the \"Description\" section of the \nhelp file and the generated help page adheres to that assumption.\n\n![lorem](docs/images/chunk_lorem.png)\n\nCurrently if there are any roxygen style comments that are \"blank\"\n\n```r\n#' This is a roxygen style comment\n#' and the following line is considered \"blank\"\n#'\n#' because the leading #' doesn't count\n```\n\nor if any lines start with \"keywords\" (such as @param, @export, ...)\nthen the automation to give it the default title and put the single chunk\nin the \"Description\" section is not applied as it is\nassumed that the user is adhering to the full roxygen standard.\n\n### ? support\n\nA little bit more information on `?` support. \nThis will only work for functions that:\n\n 1) have a docstring contained in them and \n 2) are living in the global environment.  \n\nIf it doesn't meet those requirements then `?` will fall back to the \"typical\" \nway that `?` would get interpreted.\n\nFor example if I defined\n\n```r\nlm \u003c- function(){\n    print(\"lm\")\n}\n```\n\nthis would not meet the first condition and even though it meets the second\n`?lm` would show the help file for `stats::lm` instead of saying there is no help\navailable.  If you included some docstring like so\n\n```r\nlm \u003c- function(){\n    #' lm docstring\n    #'\n    #' More docstring for lm\n    print(\"lm\")\n}\n```\nthen `?lm` will show the docstring for this function. If you wanted to view\nthe help for the 'typical' `lm` you would need to either use `help` directly or\nspecify the namespace when using `?` (i.e. `?stats::lm`)\n\n\n### help_type\n\nCurrently \"html\" and \"text\" are supported help types. The help_type \"pdf\" is\nnot supported.  If RStudio is running then the RStudio help pane will also be\nused regardless of what the help_type is set to unless options are specified to \nnot use the help pane.\n\n![Square text](docs/images/square_text.png)\n\n## Known Issues\n\n - sos\n    - Both sos and docstring overwrite `?`.  In docstring `?` becomes\n    a wrapper for `docstring` and in sos `?` calls `findFn`. The\n    order which you load sos and docstring determines which version of `?` gets\n    called if you aren't explicit about the namespace.\n    - Really I'm not too worried about this since I don't see both packages\n    being used in conjuction too often.  But I see both packages as providing\n    useful functionality for an `interactive()` session and not being used\n    within a script often.  Because of this hopefully the user will be able\n    to sort out any issues that may arise from the conflicts that can happen\n    by having more than one package mask a function.\n - devtools\n    - devtools (actually pkgload which is used by devtools) creates a drop-in \n    replacement for `?` and `help` when using `load_all()`. The `?` and `help`\n    replacements are only attached after `load_all()` is called. So if you use\n    devtools without using `load_all()` you'll never see a conflict with \n    `docstring`.  However if you do use `load_all()` after you've loaded\n    `docstring` then you might need to use the `docstring()` function to access\n    your help files.\n    - One possible workaround would be to include a \"devtools_shims\" in `search()`\n    if the user doesn't want to have the devtools version loaded. By doing this\n    the check that pkgload does to see if it should add `?` and `help` functionality\n    will come back as `FALSE`.  This would probably need to be added into docstring\n    as a package option that defaults to not overwritting the devtools stuff.\n    It's a headache all around but I shouldn't create even more unexpected behavior\n    without the user specifying that it's what they want to do.\n\n\n## Installation\n\nThe package is now hosting on CRAN [![CRAN_Status_Badge](http://www.r-pkg.org/badges/version-last-release/docstring)](https://cran.r-project.org/package=docstring)\n\nIt can easily be installed from CRAN by using the following command\n\n```r\ninstall.packages(\"docstring\")\n```\n\nYou can also download the dev version via [zip ball](https://github.com/dasonk/docstring/zipball/master) or [tar ball](https://github.com/dasonk/docstring/tarball/master), decompress and run `R CMD INSTALL` on it, or use the **devtools** package to install the development version:\n\n```r\n## Make sure your current packages are up to date\nupdate.packages()\n## devtools is required\nlibrary(devtools)\ninstall_github(\"dasonk/docstring\")\n```\n\nNote: Windows users need [Rtools](http://www.murdoch-sutherland.com/Rtools/) and [devtools](http://CRAN.R-project.org/package=devtools) to install this way.\n\n\n## Contact\n\nYou are welcome to:\n* submit suggestions and bug-reports at: \u003chttps://github.com/dasonk/docstring/issues\u003e\n* send a pull request on: \u003chttps://github.com/dasonk/docstring/\u003e\n\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdasonk%2Fdocstring","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdasonk%2Fdocstring","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdasonk%2Fdocstring/lists"}