added man file to describe the different create gist fxns

Author: sckott

DESCRIPTION

@@ -9,7 +9,7 @@ Description: Work with 'GitHub' 'gists' from 'R' (e.g.,
     your default browser, get embed code for a 'gist', list 'gist' 'commits', and
     get rate limit information when 'authenticated'. Some requests require
     authentication and some do not. 'Gists' website: https://gist.github.com/.
-Version: 0.3.1.9000
+Version: 0.3.1.9100
 Authors@R: c(
     person("Ramnath", "Vaidyanathan", role = "aut", email = "[email protected]"),
     person("Karthik", "Ram", role = "aut", email = "[email protected]"),

R/gistr-package.R

@@ -1,19 +1,19 @@
 #' R client for GitHub gists.
-#' 
-#' gistr allows you to peform actions on gists, including listing, forking, starring, creating, 
+#'
+#' gistr allows you to peform actions on gists, including listing, forking, starring, creating,
 #' deleting, updating, etc.
 #'
 #' There are two ways to authorise gistr to work with your GitHub account:
-#' 
+#'
 #' \itemize{
-#'  \item Generate a personal access token (PAT) at 
-#'  \url{https://help.github.com/articles/creating-an-access-token-for-command-line-use} 
-#'  and record it in the \code{GITHUB_PAT} envar. 
+#'  \item Generate a personal access token (PAT) at
+#'  \url{https://help.github.com/articles/creating-an-access-token-for-command-line-use}
+#'  and record it in the \code{GITHUB_PAT} envar.
 #'  \item Interactively login into your GitHub account and authorise with OAuth.
 #' }
-#' 
+#'
 #' Using the \code{GITHUB_PAT} is recommended.
-#' 
+#'
 #' @importFrom utils browseURL file.edit
 #' @importFrom methods is
 #' @importFrom stats setNames
@@ -27,3 +27,32 @@
 #' @author Karthik Ram \email{karthik.ram@@gmail.com}
 #' @keywords package
 NULL
+
+#' @title Create gists
+#'
+#' @description Creating gists in \code{gistr} can be done with any of 
+#' three functions:
+#' 
+#' \itemize{
+#'  \item \code{\link{gist_create}} - Create gists from files or code blocks, using 
+#'  the GitHub HTTP API. Because this function uses the GitHub HTTP API, it does not
+#'  work for binary files. However, you can get around this for images by using knitr's
+#'  hook to upload images to eg., imgur. In addition, it's difficult to include artifacts
+#'  from the knit-ing process.
+#'  \item \code{\link{gist_create_git}} - Create gists from files or code blocks, using 
+#'  git. Because this function uses git, you have more flexibility than with the above 
+#'  function: you can include any binary files, and can easily upload all artifacts.
+#'  \item \code{\link{gist_create_obj}} - Create gists from R objects: data.frame, list, 
+#'  character string, matrix, or numeric. Uses the GitHub HTTP API.
+#' }
+#' 
+#' It may seem a bit odd to have three separate functions for creating gists. 
+#' \code{\link{gist_create}} was created first, and was out for a bit, so when we
+#' had the idea to create gists via git (\code{\link{gist_create_git}}) and from R 
+#' objects (\code{\link{gist_create_obj}}), it made sense to have a different API for 
+#' creating gists via the HTTP API, git, and from R objects. We could have thrown 
+#' everything into \code{\link{gist_create}}, but it would have been a massive function, 
+#' with far too many parameters. 
+#'
+#' @name create_gists
+NULL

man/create_gists.Rd

@@ -0,0 +1,31 @@
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/gistr-package.R
+\name{create_gists}
+\alias{create_gists}
+\title{Create gists}
+\description{
+Creating gists in \code{gistr} can be done with any of
+three functions:
+
+\itemize{
+ \item \code{\link{gist_create}} - Create gists from files or code blocks, using
+ the GitHub HTTP API. Because this function uses the GitHub HTTP API, it does not
+ work for binary files. However, you can get around this for images by using knitr's
+ hook to upload images to eg., imgur. In addition, it's difficult to include artifacts
+ from the knit-ing process.
+ \item \code{\link{gist_create_git}} - Create gists from files or code blocks, using
+ git. Because this function uses git, you have more flexibility than with the above
+ function: you can include any binary files, and can easily upload all artifacts.
+ \item \code{\link{gist_create_obj}} - Create gists from R objects: data.frame, list,
+ character string, matrix, or numeric. Uses the GitHub HTTP API.
+}
+
+It may seem a bit odd to have three separate functions for creating gists.
+\code{\link{gist_create}} was created first, and was out for a bit, so when we
+had the idea to create gists via git (\code{\link{gist_create_git}}) and from R
+objects (\code{\link{gist_create_obj}}), it made sense to have a different API for
+creating gists via the HTTP API, git, and from R objects. We could have thrown
+everything into \code{\link{gist_create}}, but it would have been a massive function,
+with far too many parameters.
+}
+