{"id":26149114,"url":"https://github.com/liao961120/fundoc","last_synced_at":"2026-06-06T15:01:41.888Z","repository":{"id":205955355,"uuid":"712237523","full_name":"liao961120/fundoc","owner":"liao961120","description":"Quick and dirty function documentation","archived":false,"fork":false,"pushed_at":"2024-01-28T04:45:58.000Z","size":386,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-11T05:32:09.962Z","etag":null,"topics":["documentation-generator","documentation-tool","r","r-package","roxygen2"],"latest_commit_sha":null,"homepage":"http://yongfu.name/fundoc","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/liao961120.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-31T04:22:59.000Z","updated_at":"2024-04-11T09:34:11.000Z","dependencies_parsed_at":"2025-03-11T05:39:15.431Z","dependency_job_id":null,"html_url":"https://github.com/liao961120/fundoc","commit_stats":null,"previous_names":["liao961120/fundoc"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/liao961120/fundoc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liao961120%2Ffundoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liao961120%2Ffundoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liao961120%2Ffundoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liao961120%2Ffundoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/liao961120","download_url":"https://codeload.github.com/liao961120/fundoc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liao961120%2Ffundoc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33986901,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-06T02:00:07.033Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["documentation-generator","documentation-tool","r","r-package","roxygen2"],"created_at":"2025-03-11T05:28:46.445Z","updated_at":"2026-06-06T15:01:41.856Z","avatar_url":"https://github.com/liao961120.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"Quick and Dirty Function Documentation\n======================================\n\n\u003c!-- \nTo Do: add documentation for in-file DESCRIPTION\n--\u003e\n\n`fundoc` generates function documentation from R scripts that are NOT structured as an R package. \n\nR packages provides a fantastic framework to document one's work. In reality, \nhowever, many R users are unfamiliar with the highly technical workflow of \ndeveloping R packages.\n\nThis package tries to bridge the technical gap by exposing the benefits\nof [roxygen2](https://roxygen2.r-lib.org) documentation to individual R\nscripts. The purpose is not to provide a perfect tool but rather a\nminimalist gadget to get started with documenting scripts. There\nis no need to worry about structuring the R scripts into a package.\nStick to your existing workflow, document the functions, and let\n`fundoc::fundoc()` worry about generating the HTML documentation.\nThe only prerequisite is to learn the \n[basics of roxygen2](https://r-pkgs.org/man.html).\n\n\n### A Minimal Example\n\nA minimal example of function documentation generated by `fundoc` can be found [here][doc]:\n\n```r\nlibrary(fundoc)\n\nRscript = \"\n#' A Foo function\n#'\n#' Just an example\n#'\n#' @param x Character. Calling `foo()` prints out `x`.\n#' @export\n#' @examples\n#' foo('Hello World!')\nfoo \u003c- function(x) print(x)\n\"\ntmp \u003c- paste0(tempfile(), \".R\")\nwriteLines(Rscript, tmp)\n\nfundoc(scripts = tmp,\n       out_dir = \"docs\",\n       proj_name = \"fundoc\",\n       proj_title = \"Quick and Dirty Function Documentation\")\n```\n\n[doc]: https://yongfu.name/fundoc/reference/docs\n\n\n### Motivation\n\nMany functions written for data analyses or works other than\npackage development are poorly documented. One of the reasons may\nbe the lack of a framework, conventions, and associated tools for documenting \nworks other than R packages. In addition, many R users are\nsimply unaware of the possibility of turning one's work into a package\nto enhance reproducibility by leveraging the documentation and testing\nframework provided by the [devtools](https://devtools.r-lib.org) ecosystem.\nNonetheless, documentation is of great importance for all kinds of works. \n\n`fundoc` leverages the `devtools` ecosystem to generate documentation.\nIt is basically a wrapper around\n`usethis::create_package()` and `knitr::knit_rd()` to set up a temporary\npackage template for generating an HTML documentation website. In doing so,\nthe details of generating man pages is abstracted away, and users could \nfocus on documenting their individual R scripts in roxygen2 comments.\n\nNote that since `fundoc` utilizes the devtools framework, the logic of\nwriting and documenting functions in R scripts must be consistent with\nthat of package development. This may conflict with users' existing\nhabits of organizing their scripts (e.g., mixing function definitions with\nfunction calls in the same script or sourcing external scripts). Yet I would\nsuggest users adjust accordingly to the package development conventions\nsince there is a long-term benefit if you plan to stick to R.\nUnderstanding the workflow of package development is a must for anyone to \nbecome a serious R user.\n\n\n### Tips to reduce hassles with roxygen documentation\n\nBelow I provide some tips that may help users bypass obstacles they can run\ninto when documenting R scripts without the knowledge of R package development.\n\n1. Classify scripts into two types\n   - Type-I scripts for function definition\n   - Type-II scripts (or R Markdown) for analyses, communication, \n     producing results, etc.\n\n2. Define and document (with roxygen2 comments) all the functions in Type-I scripts\n   \n   Do not source external scripts in these Type-I scripts.\n   Functions defined in any of the Type-I scripts are available to all\n   Type-I scripts. In fact, you can conceive these Type-I scripts\n   as concatenating to form a single large script---you do not need to worry \n   about the dependencies between the defined functions when sourcing this\n   script into the R console.\n\n3. The previous tip suggests that in your Type-II scripts/Rmds, you\n   have to import all the functions from the Type-I scripts by\n   sourcing them all at the beginning, such as the R markdown example below:\n\n   ````rmd\n   ## Analysis\n\n   ```{r}\n   # Import Type-I scripts\n   source(\"funcDef1.R\")\n   source(\"funcDef2.R\")\n   source(\"funcDef3.R\")\n   ```\n\n   Blah blah blah\n\n   ```{r}\n   # Some analysis code (may call some functions defined in Type-I scripts)\n   ```\n   ````\n\n4. Include an `@examples` tag for EVERY function\n   \n   When documenting the functions in Type-I scripts, you might want to\n   include an `@examples` tag for each function. This would allow\n   you to demonstrate how to use the function in verbatim code.\n   `fundoc::fundoc()` helps you execute the code in the examples\n   to record and insert the output in the generated HTML documentation.\n   This amounts to the most rudimentary form of function testing.\n\n5. Include an `@export` tag for EVERY function\n   \n   For self-defined functions to run properly in the `@examples`, \n   you need to use the `pkg:::func()` notation if the function docstring \n   does not include an `@export` tag. Why? Understanding this requires \n   detail knowledge of package development. For the current purpose, \n   you can simply attach `@export` to every function to keep things simple.\n\n6. The workflow recommended here forces users to pack lots of code into functions. If you use `tidyverse` a lot, you may find the article [Programming with dplyr][u] helpful.\n\n\nIn-file DESCRIPTION\n-------------------\n\nWhen calling `fundoc::fundoc()`, users can pass in a project name (`proj_name`) and a short title for the project (`proj_title`). This information appears on the generated HTML documentation. An alternative is to include a block of metadata text---following the format of the [`DESCRIPTION`][desc] file in R packages---at the beginning of ONE of the scripts passed in to `fundoc::fundoc()`. This way, the call to `fundoc::fundoc()` becomes cleaner, and the R scripts would be self-contained with all necessary information documented.\n\nThis **in-file DESCRIPTION** is simply the text in a DESCRIPTION file prepended with roxygen comments `#' `. The DESCRIPTION text does not have to have all fields presented as in common R packages. For the DESCRIPTION text to take effect though, include at least these fields:\n\n1. `Package` (corresponds to `proj_name` in `fundoc()`)\n2. `Title` (corresponds to `proj_title` in `fundoc()`)\n3. `Version` (corresponds to `version` in `fundoc()`)\n\nBelow is an example of the in-file DESCRIPTION in `fundoc`. Remember to include  `@DESCRIPTION` to mark the presence of such an in-file DESCRIPTION.\n\n```r\n#' @DESCRIPTION\n#' Package: fundoc\n#' Title: A one line description shown in the generated HTML documentation\n#' Version: 0.0.1\n#' Authors@R: \n#'     person(\"Jane\", \"Dow\", , \"jane@dow.org\", role = c(\"aut\", \"cre\"),\n#'            comment = c(ORCID = \"0000-0001-9999-8888\"))\n#' Description: Lorem ipsum dolor sit amet, in condimentum habitant eleifend ut\n#'     urna ut. Leo, in sociis massa, sem sodales et in massa. \n#' License: MIT + file LICENSE\n#' Encoding: UTF-8\n\n#### R function definitions start below... ####\n#' A Foo function\n#'\n#' Just an example\n#'\n#' @export\n#' @examples\n#' foo()\nfoo \u003c- function() {\n  # some code\n}\n```\n\n\n[u]: https://cran.r-project.org/web/packages/dplyr/vignettes/programming.html\n[desc]: https://r-pkgs.org/description.html\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliao961120%2Ffundoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fliao961120%2Ffundoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliao961120%2Ffundoc/lists"}