7  - The DESCRIPTION file

The file creates initially when we launch the creation of our package structure contains the major metadata information. You will find fields like the name of the package, the title and description associated, version or authors. The format of this file is DCF (Debian Control Format). It looks like the YAML on several points, each line consists of a field name and a value, separated by a colon. When you have a value display on multiple lines, like the field Description, the line following the first one needs to be indented (you will see that in the example below). It’s a plain text file and like another one you can open it through a text editor (like NotePad or Visual Studio Code).

For our package created before, this is the initial DESCRIPTION file.

Package: macfly
Title: What the Package Does (One Line, Title Case)
Version: 0.0.0.9000
Authors@R: 
    person("First", "Last", , "first.last@example.com", role = c("aut", "cre"))
Description: What the package does (one paragraph).
License: `use_mit_license()`, `use_gpl3_license()` or friends to pick a
    license
Encoding: UTF-8
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.3.2

To update this file you have two possibilities, open the file and modify it by hand or use the R package desc [1] to manipulate it by command lines. In the following part, we will use functions of this package to reduce as possible typing error.

7.1 Fields Title and Description

Like name suggest, Title is one line description of the package. It should be plain text (no markup), capitalized like a title, and not end in a period. Shorter is better and anyway, listings will often truncate the title to 65 characters.

Description field is one (and only one) paragraph more detailed than the Title field. You can use multiple sentences and it’s recommended to use multiple lines. Each line must be no more than 80 characters wide and indent the new line with 4 spaces.

It’s important to find a good title and description because it’s soemthing that people see in first, especially if you submit your package on CRAN (it’s display on the package CRAN website).

For our example, I used the code below. You can modify it according to our needs.

library(desc)
# By default the function read the DESCRIPTION file of the current working directory
description_file <- desc()
# For modify the title 
description_file$set(Title = "My Anwesone paCkage For Learning with Yearning",
                     Description = "An example of R package development with functions and all the stuff around to increase the joy of writing our own processes.")

You will find at the end of this page, the full render of my DESCRIPTION file.

7.2 Field Author

The field Authors@R inside the DESCRIPTION file identify package’s authors and contributors. This is a very important information because with that you know whom to contact if you are any troubles with the package. In comparaison with the other field, this one contains executable R code rather than plain text. You could find also a declaration of authors like below.

Author: FirstName LastName [aut, cre]

It’s the classic way but I highly recommend using the modern one with Authors@R because you will be able to increase the amount of information inside, like the affiliations or the ORCID number. Furthermore, it’s the format recommended by CRAN. In addition, it integrate the function person() which hold information about individuals such as their name and email address and display them in the proper way in R.