Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
krlmlr opened this issue Jun 3, 2015 · 8 comments
Closed

Comments

@krlmlr
Copy link
Member

@krlmlr krlmlr commented Jun 3, 2015

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
Copy link
Member

@hadley hadley commented Oct 7, 2015

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
Copy link
Member

@hadley hadley commented Oct 7, 2015

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
Copy link
Member Author

@krlmlr krlmlr commented Oct 7, 2015

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

@hadley
Copy link
Member

@hadley hadley commented Oct 7, 2015

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
Copy link
Member

@hadley hadley commented Oct 7, 2015

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
Copy link
Member

@hadley hadley commented Oct 7, 2015

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

@krlmlr
Copy link
Member Author

@krlmlr krlmlr commented Oct 7, 2015

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
Copy link
Member

@hadley hadley commented Oct 7, 2015

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
2 participants