Write function documentation in Markdown

[luukvdmeer]

It may be a bit of work to convert, but I think it will pay off in the longterm. Function documentation will be easier to write and read. See https://roxygen2.r-lib.org/articles/markdown.html

[agila5]

Dear all, I prepared the following script to convert the existing docs into markdown format. I copy it here since I'm not sure about all details and I'd like a double-check. Prerequisites: 1) Add an empty trailing line at the end of R/utils.R; 2) Add Roxygen: list(markdown = TRUE) in the DESCRIPTION file.

The script:

my_files <- list.files("R", full.names = TRUE)

for (file in my_files) {
  docs <- readLines(file)

  # Replace fixed R code
  docs <- gsub("\\code{...}",        "`...`", docs, fixed = TRUE)
  docs <- gsub("\\code{data.frame}", "`data.frame`", docs, fixed = TRUE)
  docs <- gsub("\\code{FALSE}",      "`FALSE`", docs, fixed = TRUE)
  docs <- gsub("\\code{Inf}",        "`Inf`", docs, fixed = TRUE)
  docs <- gsub("\\code{NaN}",        "`NaN`", docs, fixed = TRUE)
  docs <- gsub("\\code{NA}",         "`NA`", docs, fixed = TRUE)
  docs <- gsub("\\code{NULL}",       "`NULL`", docs, fixed = TRUE)
  docs <- gsub("\\code{TRUE}",       "`TRUE`", docs, fixed = TRUE)

  # Replace standard text written as code just for emphasis
  docs <- gsub("\\code{.orig_data}",        "`.orig_data`", docs, fixed = TRUE)
  docs <- gsub("\\code{'agr'}",             "`'agr'`", docs, fixed = TRUE)
  docs <- gsub("\\code{agr}",               "`agr`", docs, fixed = TRUE)
  docs <- gsub("\\code{'all_shortest'}",    "`'all_shortest'`", docs, fixed = TRUE)
  docs <- gsub("\\code{'all_simple'}",      "`'all_simple'`", docs, fixed = TRUE)
  docs <- gsub("\\code{edge_paths}",        "`edge_paths`", docs, fixed = TRUE)
  docs <- gsub("\\code{from}",              "`from`", docs, fixed = TRUE)
  docs <- gsub("\\code{ggplot2}",           "`ggplot2`", docs, fixed = TRUE)
  docs <- gsub("\\code{LINESTRING}",        "`LINESTRING`", docs, fixed = TRUE)
  docs <- gsub("\\code{morphed_sfnetwork}", "`morphed_sfnetwork`", docs, fixed = TRUE)
  docs <- gsub("\\code{name}",              "`name`", docs, fixed = TRUE)
  docs <- gsub("\\code{node_key}",          "`node_key`", docs, fixed = TRUE)
  docs <- gsub("\\code{node_paths}",        "`node_paths`", docs, fixed = TRUE)
  docs <- gsub("\\code{POINT}",             "`POINT`", docs, fixed = TRUE)
  docs <- gsub("\\code{predecessors}",      "`predecessors`", docs, fixed = TRUE)
  docs <- gsub("\\code{s2}",                "`s2`", docs, fixed = TRUE)
  docs <- gsub("\\code{sf}",                "`sf`", docs, fixed = TRUE)
  docs <- gsub("\\code{'sf_column'}",       "`'sf_column'`", docs, fixed = TRUE)
  docs <- gsub("\\code{sf_column}",         "`sf_column`", docs, fixed = TRUE)
  docs <- gsub("\\code{sfnetworks}",        "`sfnetworks`", docs, fixed = TRUE)
  docs <- gsub("\\code{sfnetwork}",         "`sfnetwork`", docs, fixed = TRUE)
  docs <- gsub("\\code{'shortest'}",        "`'shortest'`", docs, fixed = TRUE)
  docs <- gsub("\\code{spatstat}",          "`spatstat`", docs, fixed = TRUE)
  docs <- gsub("\\code{'tbl_df'}",          "`'tbl_df'`", docs, fixed = TRUE)
  docs <- gsub("\\code{tidygraph}",         "`tidygraph`", docs, fixed = TRUE)
  docs <- gsub("\\code{to}",                "`to`", docs, fixed = TRUE)
  docs <- gsub("\\code{type}",              "`type`", docs, fixed = TRUE)
  docs <- gsub("\\code{weight}",            "`weight`", docs, fixed = TRUE)
  docs <- gsub("\\code{x}",                 "`x`", docs, fixed = TRUE)
  docs <- gsub("\\code{y}",                 "`y`", docs, fixed = TRUE)

  # Links to existing functions
  docs <- gsub("\\code{\\link{as_sfnetwork}}",           "[as_sfnetwork()]", docs, fixed = TRUE)
  docs <- gsub("\\code{graph_attribute_names}",          "[graph_attribute_names()]", docs, fixed = TRUE)
  docs <- gsub("\\code{edge_is_within_distance}",        "[edge_is_within_distance()]", docs, fixed = TRUE)
  docs <- gsub("\\code{node_is_within_distance}",        "[node_is_within_distance()]", docs, fixed = TRUE)
  docs <- gsub("\\code{spatial_attribute_names}",        "[spatial_attribute_names()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link{st_network_cost}}",        "[st_network_cost()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link{st_network_paths}}",       "[st_network_paths()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link{to_spatial_subdivision}}", "[to_spatial_subdivision()]", docs, fixed = TRUE)

  # Links to external functions
  docs <- gsub("\\code{\\link[dplyr]{arrange}}",                "[dplyr::arrange()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[dplyr]{bind_rows}}",              "[dplyr::bind_rows()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[ggplot2]{autoplot}}",             "[ggplot2::autoplot()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[igraph]{all_shortest_paths}}",    "[igraph::all_shortest_paths()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[igraph]{all_simple_paths}}",      "[igraph::all_simple_paths()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[igraph]{distances}}",             "[igraph::distances()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[igraph]{shortest_paths}}",        "[igraph::shortest_paths()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[lwgeom]{st_geod_azimuth}}",       "[lwgeom::st_geod_azimuth()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[sf]{st_as_sf}}",                  "[sf::st_as_sf()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[sf]{st_bbox}}",                   "[sf::st_bbox()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[sf]{st_crop}}",                   "[sf::st_crop()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[sf]{st_distance}}",               "[sf::st_distance()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[sf]{st_equals}}",                 "[sf::st_equals()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[sf]{st_join}}",                   "[sf::st_join()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[sf]{st_length}}",                 "[sf::st_length()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[sf]{st_nearest_feature}}",        "[sf::st_nearest_feature()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[sf]{st_transform}}",              "[sf::st_transform()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[tibble]{as_tibble}}",             "[tibble::as_tibble()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[tibble]{tbl_df}}",                "[tibble::tbl_df()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[tidygraph]{as_tbl_graph}}",       "[tidygraph::as_tbl_graph()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[tidygraph]{convert}}",            "[tidygraph::convert()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[tidygraph]{crystallise}}",        "[tidygraph::crystallise()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[tidygraph]{filter}}",             "[tidygraph::filter()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[tidygraph]{graph_join}}",         "[tidygraph::graph_join()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[tidygraph]{morph}}",              "[tidygraph::morph()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[tidygraph]{mutate}}",             "[tidygraph::mutate()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[tidygraph]{node_distance_from}}", "[tidygraph::node_distance_from()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[tidygraph]{node_distance_to}}",   "[tidygraph::node_distance_to()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[tidygraph]{to_directed}}",        "[tidygraph::to_directed()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[tidygraph]{to_subgraph}}",        "[tidygraph::to_subgraph()]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[tidygraph]{with_graph}}",         "[tidygraph::with_graph()]", docs, fixed = TRUE)

  # Links to existing classes
  docs <- gsub("\\code{\\link{sfnetwork}}", "[`sfnetwork`]", docs, fixed = TRUE)

  # Links to external classes or docs pages
  docs <- gsub("\\code{\\link[igraph]{igraph}}",                       "[`igraph::igraph`]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[igraph]{igraph-attribute-combination}}", "[`igraph::igraph-attribute-combination`]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[ggplot2]{ggplot}}",                      "[`ggplot2::ggplot`]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[sf]{geos_binary_pred}}",                 "[`sf::geos_binary_pred`]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[sf]{NA_agr_}}",                          "[`sf::NA_agr_`]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[sf]{sf}}",                               "[`sf::sf`]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[sf]{sfc}}",                              "[`sf::sfc`]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[spatstat.linnet]{linnet}}",              "[`spatstat.linnet::linnet`]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[tibble]{tibble}}",                       "[`tibble::tibble`]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[tidygraph]{morphers}}",                  "[`tidygraph::morphers`]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[tidygraph]{tbl_graph}}",                 "[`tidygraph::tbl_graph`]", docs, fixed = TRUE)
  docs <- gsub("\\code{\\link[units]{units}}",                         "[`units::units`]", docs, fixed = TRUE)

  # Not sure how to convert the following with :
  # 1. "\\code{\\link[sf:st_bbox]{bbox}}" 
  # 2. "\\code{\\link[tidygraph:tidygraph-package]{tidygraph}}"
  # 3. "\\code{\\link[sf:plot]{plot.sf}}"
  # 4. "\\code{\\link[sf:st]{sfg}}" 
  # 5. "\\code{\\link[igraph:all_simple_paths]{igraph}}"
  # 6. "\\code{\\link[igraph:shortest_paths]{igraph}}"

  # Moreover
  # 1. \\code{st_is_within_distance} (missing link?)

  cat(docs, file = file, sep = "\n")
}

The existing patterns were derived using regexp while I manually tried to deduce the "translations". The last two blocks include the more uncertain conversions.