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

Ignore roxygen2 generated files #3373

Merged
merged 1 commit into from Jan 3, 2017

Conversation

Projects
None yet
3 participants
@yutannihilation
Contributor

yutannihilation commented Dec 8, 2016

Disclaimer: I'm a newbie to Ruby.

In R, roxygen2 is a de facto standard of document generation. The generated documents are typically starts with this line:

% Generated by roxygen2: do not edit by hand

For a real example, please see this one: https://github.com/tidyverse/ggplot2/blob/f6f9f9de41c48382c70cbccc253db198e3cdc128/man/layer.Rd#L1

This pull request make linguist to ignore these generated documents.

@pchaigno

Impeccable pull request 👍

@pchaigno

This comment has been minimized.

Show comment
Hide comment
@pchaigno

pchaigno Dec 8, 2016

Collaborator

It's orthogonal to this pull request, but it looks like .Rd files do not actually have a R syntax. Is that TeX?

Collaborator

pchaigno commented Dec 8, 2016

It's orthogonal to this pull request, but it looks like .Rd files do not actually have a R syntax. Is that TeX?

@yutannihilation

This comment has been minimized.

Show comment
Hide comment
@yutannihilation

yutannihilation Dec 8, 2016

Contributor

Wow, thanks!

Yes .Rd files are not R files, but a kind of TeX. They are purely used for documentation purpose. As this syntax is very different from R syntax and we (I believe I'm not the only one...), R people, are too lazy to learn this, it is common practice to auto-generate .Rd files from comments embedded in R files.

For example, this:

#' Import a module into the current scope
#'
#' \code{module = import('module')} imports a specified module and makes its
#' code available via the environment-like object it returns.
#'
#' @param module an identifier specifying the full module path
#' @param attach if \code{TRUE}, attach the newly loaded module to the object
#'      search path (see \code{Details})
#' @param attach_operators if \code{TRUE}, attach operators of module to the
#'      object search path, even if \code{attach} is \code{FALSE}
#' @return the loaded module environment (invisible)
...snip...

will be converted into this by roxygen2:

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hello.R
\name{import}
\alias{import}
\title{Import a module into the current scope}
\usage{
import(module, attach, attach_operators = TRUE)
}
\arguments{
\item{module}{an identifier specifying the full module path}

\item{attach}{if \code{TRUE}, attach the newly loaded module to the object
search path (see \code{Details})}

\item{attach_operators}{if \code{TRUE}, attach operators of module to the
object search path, even if \code{attach} is \code{FALSE}}
}
\value{
the loaded module environment (invisible)
}
...snip...

So, the diffs of the documentation part will be shown both in .R file and the corresponding .Rd file redundantly. I believe we can safely ignore .Rd :)

Contributor

yutannihilation commented Dec 8, 2016

Wow, thanks!

Yes .Rd files are not R files, but a kind of TeX. They are purely used for documentation purpose. As this syntax is very different from R syntax and we (I believe I'm not the only one...), R people, are too lazy to learn this, it is common practice to auto-generate .Rd files from comments embedded in R files.

For example, this:

#' Import a module into the current scope
#'
#' \code{module = import('module')} imports a specified module and makes its
#' code available via the environment-like object it returns.
#'
#' @param module an identifier specifying the full module path
#' @param attach if \code{TRUE}, attach the newly loaded module to the object
#'      search path (see \code{Details})
#' @param attach_operators if \code{TRUE}, attach operators of module to the
#'      object search path, even if \code{attach} is \code{FALSE}
#' @return the loaded module environment (invisible)
...snip...

will be converted into this by roxygen2:

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hello.R
\name{import}
\alias{import}
\title{Import a module into the current scope}
\usage{
import(module, attach, attach_operators = TRUE)
}
\arguments{
\item{module}{an identifier specifying the full module path}

\item{attach}{if \code{TRUE}, attach the newly loaded module to the object
search path (see \code{Details})}

\item{attach_operators}{if \code{TRUE}, attach operators of module to the
object search path, even if \code{attach} is \code{FALSE}}
}
\value{
the loaded module environment (invisible)
}
...snip...

So, the diffs of the documentation part will be shown both in .R file and the corresponding .Rd file redundantly. I believe we can safely ignore .Rd :)

@brblck brblck merged commit 1c4baf6 into github:master Jan 3, 2017

2 checks passed

GitHub CLA @yutannihilation has accepted the GitHub Contributor License Agreement.
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details

@yutannihilation yutannihilation deleted the yutannihilation:ignore-roxygen2-generated-files branch Jan 30, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment