Proposal: @docType package assigns title and description from the DESCRIPTION file

[krlmlr]

An .R file with the following contents

#' @name PackageName
#' @docType package
NULL

should create the PackageName.Rd with \title and \description set from the DESCRIPTION file. Of course, both can be overridden manually. One can use #' @details to add further information.

Use case: Automatic creation of consistent and meaningful package documentation files which are useful, e.g., for data-only packages.

[hadley]

That seems reasonable to me. Is @name even necessary? You should be able to pull that from the description too (although that might make the code considerably more complicated ... yeah looks like that would require a lot of messing around)

[hadley]

It's relatively straightforward to modify process.docType() to add the extra information:

process.docType <- function(partitum, base_path) {
  doctype <- partitum$docType

  if (is.null(doctype)) return()
  tags <- list(new_tag("docType", doctype))

  if (doctype == "package") {
    name <- partitum$name
    if (!str_detect(name, "-package")) {
      tags <- c(tags, new_tag("alias", paste0(name, "-package")))
    }

    desc <- read.description(file.path(base_path, "DESCRIPTION"))
    if (is.null(partitum$title)) {
      tags <- c(tags, new_tag("title", desc$Title))
    }

    if (is.null(partitum$descr)) {
      tags <- c(tags, new_tag("description", desc$Description))
    }

  }

  tags
}

But a better approach would be to come up with a sentinel value so that you could do (e.g.):

#' Title
packageName()

And roxygen could automatically figure out you want to document the package, and could then generate defaults for name, docType, title, and description. (You'd still need one roxygen comment in order to trigger documentation generation)

[krlmlr]

Where would this packageName() function live? Honestly, I like the simpler docType approach more.

[hadley]

packageName() already exists - it's just used as a sentinel value. I don't think the docType approach is simpler because it tangles up processing rds with figuring out defaults, and hence makes default values for package objects work very differently to S3 and S4 objects.

[hadley]

i.e. this proposal makes packages an official top class object understood by roxygen in the same way that functions, methods, classes, data, etc are.

[hadley]

I don't think packageName() is the right value, but I think it will be easier to understand than documenting NULL.

[krlmlr]

How about "package:roxygen2" as a sentinel value for this package? I'll prepare a pull request, we can discuss the sentinel value later.

[hadley]

Something like that sounds good. "PACKAGE" would be another option.