Step 9: editing the help files

Now comes the tedious task of editing these help files. To tell the truth It took me a few tries to get the editing correct. Since the files have a well defined syntax I’m pretty sure that building a WYSIWYG editor wouldn’t be that hard, but for now I’ll just edit the files in RStudio and show you what I did. The editing job is not yet complete but  you will get the idea.

Lets start with the description File.

Package: mypkg
Type: Package
Title: What the package does (short line)
Version: 1.0
Date: 2011-06-08
Author: Who wrote it
Maintainer: Who to complain to <yourfault@somewhere.net>
Description: More about what it does (maybe more than one line)
License: What license is it under?
LazyLoad: yes

We will edit this to look like this

Package: mypkg
Type: Package
Title: Moshers first test package
Version: 1.0
Date: 2011-06-08
Author: Steven Mosher
Maintainer: Steven Mosher <moshersteven@gmail.com>
Description: This package performs a few functions and demonstrates how
  to build a package
License: GPL 2
LazyLoad: yes

Obviously, you should fill in your own information. Please see the documentation guide for specific rules on writing documentation. Next, up we will edit some of the other files. We will start with the Package description.  It looks like this to start with. One thing I had to learn by trial and error ( again, RTFM ) was which fields were required and which were optional. If you try to build without editing this file you will generate warnings.

\name{mypkg-package}
\alias{mypkg-package}
\alias{mypkg}
\docType{package}
\title{
What the package does (short line)
~~ package title ~~
}
\description{
More about what it does (maybe more than one line)
~~ A concise (1-5 lines) description of the package ~~
}
\details{
\tabular{ll}{
Package: \tab mypkg\cr
Type: \tab Package\cr
Version: \tab 1.0\cr
Date: \tab 2011-06-08\cr
License: \tab What license is it under?\cr
LazyLoad: \tab yes\cr
}
~~ An overview of how to use the package, including the most important functions ~~
}
\author{
Who wrote it

Maintainer: Who to complain to <yourfault@somewhere.net>
~~ The author and/or maintainer of the package ~~
}
\references{
~~ Literature or other references for background information ~~
}
~~ Optionally other standard keywords, one per line, from file KEYWORDS in the R ~~
~~ documentation directory ~~
\keyword{ package }
\seealso{
~~ Optional links to other man pages, e.g. ~~
~~ \code{\link[<pkg>:<pkg>-package]{<pkg>}} ~~
}
\examples{
~~ simple examples of the most important functions ~~
}

What happens if you insist upon building and trying to check this this package WITHOUT editing the help files? This Happens:

If you do not edit these files and then try to build the package  ( Rcmd build mypkg) and then Check the package (Rcmd check mypkg) you will  fail.  Lets have a look at that log.

* installing *source* package 'mypkg' ...
** R
** data
** preparing package for lazy loading
** help
Warning: C:/Users/steve/Documents/TestPackage/mypkg/man/mypkg-package.Rd:33: All text must be in a section
Warning: C:/Users/steve/Documents/TestPackage/mypkg/man/mypkg-package.Rd:34: All text must be in a section
*** installing help indices
Error in Rd_info(db[[i]]) :
  missing/empty \title field in 'C:/Users/steve/Documents/TestPackage/mypkg/man/d.Rd'
Rd files must have a non-empty \title.
See chapter 'Writing R documentation' in manual 'Writing R Extensions'.
* removing 'C:/Users/steve/Documents/TestPackage/mypkg.Rcheck/mypkg'

As you can see I’ve generated warnings and errors because I failed to edit the files properly.   Lets dive in and edit those files and then we can build and check successfully.

So, returning to the mypkg-package.Rd file, I’ve loaded that up and edited it to get rid of the text that is not in sections. I also added some simple descriptions and removed some of the optional elements. Here is what It looks like

\name{mypkg-package}
\alias{mypkg-package}
\alias{mypkg}
\docType{package}
\title{ This Package tests my ability to follow instructions}
\description{ This package is built by copying the sample code for
  package.skeleton() and then editing the help files
}
\details{
\tabular{ll}{
Package: \tab mypkg\cr
Type: \tab Package\cr
Version: \tab 1.0\cr
Date: \tab 2011-06-08\cr
License: \tab GPL 2\cr
LazyLoad: \tab yes\cr
}

}
\author{ Steven Mosher

Maintainer: Steven Mosher <moshersteven@gmail.com>

}
\references{ Package source is in the help file for package.skeleton}

\keyword{ package }

\examples{
test <- f(x=1,y=2)

}

Next, I have to edit all the files for each function and the help file for the data

\name{d}
\alias{d}
\docType{data}
\title{ A Sample Data object}
\description{ The datset for this test is a simple data.frame with two elements}
\usage{data(d)}
\format{
  A data frame with 1 observations on the following 2 variables.
  \describe{
    \item{\code{a}}{a numeric vector}
    \item{\code{b}}{a numeric vector}
  }
}
\details{ There are no more details required}

\source{ The source of the data is the help file for skeleton}

\references{ There are no references}

\examples{
data(d)
## maybe str(d) ; plot(d) ...
}
\keyword{datasets}

Below find the “e” dataset

\name{e}
\alias{e}
\docType{data}
\title{ Generate 1000 variates of a normal}

\description{ This generates rnorm(1000)}

\usage{data(e)}
\format{
  The format is:
 num [1:1000] 0.653 -0.188 -0.469 -1.519 0.243 ...
}
\details{ Not any details needed}

\source{ The skeleton example code}

\references{ No references}

\examples{
data(e)
## maybe str(e) ; plot(e) ...
}
\keyword{datasets}

Now my edited version of the “g” function

\name{g}
\alias{g}

\title{ Test Function}

\description{ This function subtracts}

\usage{
g(x, y)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
  \item{x}{ First variable}

  \item{y}{ Second Variable}

}
\details{ No details required }

\value{ Numeric is returned}

\references{ You guessed it . the help file of skelelon }

\author{ Steven Mosher}

\note{  No notes for this function either }

\examples{
x <- 2
y <- 4
print(g(x,y))
}

\keyword{ arith }

Now,  the “f” function

 
\name{f}
\alias{f}

\title{ Addition Function}

\description{ The function adds two numbers}

\usage{
f(x, y)
}

\arguments{
  \item{x}{ The first argument for addition}

  \item{y}{ The second item for addition}

}
\details{ No more details required. It adds two numbers}

\value{ Returns a number that is the sum }

\references{ package.Skeleton code}

\author{ Steven Mosher} 

\note{ There are no further notes}

\examples{
  x <- 1
  y <- 3
  test <- f(x,y)
  print(test)
}

\keyword{ arith }

Now onto step 10 and we are ready to build