R documentation format

[adamhsparks]

Related to my review, https://github.com/openjournals/joss-reviews/issues/2948,

The Guidelines for Rd files state that \title sections should be capitalised and not end in a period, see: https://developer.r-project.org/Rds.html

Currently, the ROxygen sections of the .R files are in this format: first Second Third Word or first second third word

It should instead be: First second third word unless there are proper names in the title for each function being documented.

[adamhsparks]

Further comments on the documentation format.

The https://developer.r-project.org/Rds.html guidelines states:

Always use <- rather than = for assignments.

This example shows an incorrect usage of = in place of <-.

#' @examples
#' \dontrun{
#' voivodeship_geom = borders_get(voivodeship = "lubuskie") # 494 KB
#' county_geom = borders_get(county = "Sopot") # 18 KB
#' commune_geom = borders_get(commune = c("Hel", "Krynica Morska")) # 11 KB
#' }

These guidelines are not hard-fast for package writers, but they do follow the base-R guidelines, so I'd suggest it's worth considering them both.

[adamhsparks]

The term "Boolean" is misspelled in the documentation as "boolean" in at least one spot that I caught.

[kadyb]

The Guidelines for Rd files state that \title sections should be capitalised and not end in a period, see: https://developer.r-project.org/Rds.html

Fixed in https://github.com/kadyb/rgugik/pull/59.

[kadyb]

Always use <- rather than = for assignments.

If possible, we would prefer to stay with the = for the assignment to be consistent with our code and vignettes. In my opinion, more and more users and developers are using = instead of the <-, which makes writing code much easier. This has a great advantage when other languages, such as C++ or Python, are used in the project in addition to R.

[adamhsparks]

To be clear, this issue is not about using it in the package but rather in the examples in the documentation itself where it's unconventional to use =. But as I said, it's not hard-fast. Just more normal for R, which as you noted is not Python or C++.

[kadyb]

Yeah, I just mean that I would like to keep the same assignment character in all places (including examples). This is mainly due to my habit, as I also use Python. We are aware that a lot of R users prefer the <- character. As I mentioned before, we have noticed that more and more users are simply using = and perhaps this will be the default assignment character in R in the future.

For references, you can check books focused on spatial data analysis (Geocomputation with R, Spatial Data Science), examples in sf and stars packages or this interesting post.

Nevertheless, thanks for this suggestion and understanding!