allow setting startType for documenting realizations

.buildlibrary

@@ -1,4 +1,4 @@
-ValidationKey: '2815670'
+ValidationKey: '2842128'
 AutocreateReadme: yes
 AcceptedWarnings:
 - 'Warning: package ''.*'' was built under R version'

CITATION.cff

@@ -2,8 +2,8 @@ cff-version: 1.2.0
 message: If you use this software, please cite it using the metadata from this file.
 type: software
 title: 'goxygen: In-Code Documentation for ''GAMS'''
-version: 1.4.3
-date-released: '2023-11-29'
+version: 1.4.4
+date-released: '2024-01-15'
 abstract: A collection of tools which extract a model documentation from 'GAMS' code
   and comments. In order to use the package you need to install 'pandoc' and 'pandoc-citeproc'
   first (<https://pandoc.org/>).

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: goxygen
 Type: Package
 Title: In-Code Documentation for 'GAMS'
-Version: 1.4.3
-Date: 2023-11-29
+Version: 1.4.4
+Date: 2024-01-15
 Authors@R: c(person("Jan Philipp", "Dietrich", email = "[email protected]", role = c("aut","cre")),
              person("Kristine", "Karstens", email = "[email protected]", role = "aut"),
              person("David", "Klein", email = "[email protected]", role = "aut"),
@@ -34,5 +34,5 @@ BugReports: https://github.com/pik-piam/goxygen/issues
 License: BSD_2_clause + file LICENSE
 Encoding: UTF-8
 LazyData: no
-RoxygenNote: 7.2.3
+RoxygenNote: 7.3.0
 VignetteBuilder: knitr

R/createListModularCode.R

@@ -10,6 +10,10 @@
 #' @param includeCore Boolean whether core should be included or not, default=FALSE
 #' @param mainfile main file of the model
 #' @param docfolder folder the documentation should be written to relative to model folder
+#' @param startType input parameter for \code{\link{extractDocumentation}} to be passed
+#'        when extracting documentation from realizations. Defaults to "equations",
+#'        meaning that documentation in realizations should be interpreted as equations
+#'        documentation, if no identifier is set.
 #' @author Jan Philipp Dietrich
 #' @importFrom stringi stri_extract_all_regex stri_replace_all_regex stri_write_lines
 #' @importFrom gms codeCheck modules_interfaceplot is.modularGAMS
@@ -20,8 +24,10 @@
 #' @importFrom withr local_dir
 #' @seealso \code{\link{codeCheck}}
 
-createListModularCode <- function(cc, interfaces, path = ".", citation = NULL, unitPattern = c("\\(", "\\)"), # nolint
-                                  includeCore = FALSE, mainfile = "main.gms", docfolder = "doc") {
+createListModularCode <- function(cc, interfaces, path = ".", citation = NULL, # nolint
+                                  unitPattern = c("\\(", "\\)"), includeCore = FALSE,
+                                  mainfile = "main.gms", docfolder = "doc",
+                                  startType = "equations") {
 
   local_dir(path)
 
@@ -150,15 +156,15 @@ createListModularCode <- function(cc, interfaces, path = ".", citation = NULL, u
     return(out)
   }
 
-  collectRealizations <- function(m, cc, modules = "modules/") {
+  collectRealizations <- function(m, cc, startType, modules = "modules/") {
     m <- sub("[0-9]*_", "", m)
     if (m == "core") {
       outSub <- list()
       outSub$realizations <- list()
       files <- list.files(path = "core", pattern = "\\.gms")
       paths <- file.path("core", files)
 
-      outSub$realizations[["core"]] <- extractDocumentation(paths, start_type = "equations")
+      outSub$realizations[["core"]] <- extractDocumentation(paths, startType = startType)
 
     } else {
       rea <- strsplit(cc$modulesInfo[m, "realizations"], ",")[[1]]
@@ -180,7 +186,7 @@ createListModularCode <- function(cc, interfaces, path = ".", citation = NULL, u
         # mentioned files will be added at the end.
         paths <- union(intersect(mentionedPaths, existingPaths), existingPaths)
 
-        outSub$realizations[[r]] <- extractDocumentation(paths, start_type = "equations")
+        outSub$realizations[[r]] <- extractDocumentation(paths, startType = startType)
       }
     }
     return(outSub)
@@ -216,7 +222,7 @@ createListModularCode <- function(cc, interfaces, path = ".", citation = NULL, u
   }
 
   for (m in mLoop) {
-    realizations <- collectRealizations(m, cc)
+    realizations <- collectRealizations(m, cc, startType)
     extract <- flattenPageBlockList(realizations)
 
     realizations <- extract$blocks

R/extractDocumentation.R

@@ -6,7 +6,7 @@
 #'
 #'
 #' @param path path to the file(s) which should be evaluated
-#' @param start_type set type for first line of code. This can be useful
+#' @param startType set type for first line of code. This can be useful
 #' to extract documentation even if no documentation type has been set (e.g
 #' reading equations.gms as type realization)
 #' @param comment comment chars used for documentation comments
@@ -27,12 +27,12 @@
 #'
 #' @export
 
-extractDocumentation <- function(path, start_type = NULL, comment = "*'") { # nolint
+extractDocumentation <- function(path, startType = NULL, comment = "*'") { # nolint
 
   if (length(path) > 1) {
     out <- list()
     for (p in path) {
-      out <- append(out, extractDocumentation(p, start_type = start_type, comment = comment))
+      out <- append(out, extractDocumentation(p, startType = startType, comment = comment))
     }
     return(out)
   }
@@ -119,8 +119,8 @@ extractDocumentation <- function(path, start_type = NULL, comment = "*'") { # no
   if (!file.exists(path)) return(list())
   x <- readLines(path, warn = FALSE)
   x <- removeComments(x, comment)
-  if (!is.null(start_type)) {
-    x <- c(paste0(comment, " @", start_type, " "), x)
+  if (!is.null(startType)) {
+    x <- c(paste0(comment, " @", startType, " "), x)
   }
 
   regex <- paste0("^", escapeRegex(comment), " @[a-z]*( |(\\{.+\\})|$)")

R/goxygen.R

@@ -50,6 +50,7 @@
 #' @param unitPattern pattern that is usedto identify the unit in the description, default =c("\\(","\\)")
 #' @param includeCore boolean whether core should be included or not, default=FALSE
 #' @param mainfile main file of the model
+#' @param startType input parameter for \code{\link{createListModularCode}}, default = "equations"
 #' @param ... optional arguments to \code{\link[gms]{interfaceplot}}, passed via
 #' \code{\link[gms]{modules_interfaceplot}}.
 #'
@@ -82,6 +83,7 @@ goxygen <- function(path = ".",
                     unitPattern = c("\\(", "\\)"),
                     includeCore = FALSE,
                     mainfile = "main.gms",
+                    startType = "equations",
                     ...) {
   local_dir(path)
 
@@ -126,7 +128,8 @@ goxygen <- function(path = ".",
     }
     full <- createListModularCode(cc = cc, interfaces = interfaces, path = ".", citation = citation,
                                   unitPattern = unitPattern, includeCore = includeCore,
-                                  mainfile = mainfile, docfolder = docfolder)
+                                  mainfile = mainfile, docfolder = docfolder,
+                                  startType = startType)
   } else {
     copyimages(docfolder, paths = list.files(pattern = "\\.(jpg|png)$", recursive = TRUE))
     full <- createListSimpleCode(path = ".", citation = citation, mainfile = mainfile)

README.md

@@ -1,6 +1,6 @@
 # In-Code Documentation for 'GAMS'
 
-R package **goxygen**, version **1.4.3**
+R package **goxygen**, version **1.4.4**
 
 [![CRAN status](https://www.r-pkg.org/badges/version/goxygen)](https://cran.r-project.org/package=goxygen) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.1411404.svg)](https://doi.org/10.5281/zenodo.1411404) [![R build status](https://github.com/pik-piam/goxygen/workflows/check/badge.svg)](https://github.com/pik-piam/goxygen/actions) [![codecov](https://codecov.io/gh/pik-piam/goxygen/branch/master/graph/badge.svg)](https://app.codecov.io/gh/pik-piam/goxygen) [![r-universe](https://pik-piam.r-universe.dev/badges/goxygen)](https://pik-piam.r-universe.dev/builds)
 
@@ -48,16 +48,16 @@ In case of questions / problems please contact Jan Philipp Dietrich <dietrich@pi
 
 To cite package **goxygen** in publications use:
 
-Dietrich J, Karstens K, Klein D, Baumstark L, Benke F (2023). _goxygen: In-Code Documentation for 'GAMS'_. doi:10.5281/zenodo.1411404 <https://doi.org/10.5281/zenodo.1411404>, R package version 1.4.3, <https://github.com/pik-piam/goxygen>.
+Dietrich J, Karstens K, Klein D, Baumstark L, Benke F (2024). _goxygen: In-Code Documentation for 'GAMS'_. doi:10.5281/zenodo.1411404 <https://doi.org/10.5281/zenodo.1411404>, R package version 1.4.4, <https://github.com/pik-piam/goxygen>.
 
 A BibTeX entry for LaTeX users is
 
  ```latex
 @Manual{,
   title = {goxygen: In-Code Documentation for 'GAMS'},
   author = {Jan Philipp Dietrich and Kristine Karstens and David Klein and Lavinia Baumstark and Falk Benke},
-  year = {2023},
-  note = {R package version 1.4.3},
+  year = {2024},
+  note = {R package version 1.4.4},
   doi = {10.5281/zenodo.1411404},
   url = {https://github.com/pik-piam/goxygen},
 }