diff --git a/.gitignore b/.gitignore
new file mode 100644
index 00000000000..807ea251739
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,3 @@
+.Rproj.user
+.Rhistory
+.RData
diff --git a/ProgrammingAssignment2.Rproj b/ProgrammingAssignment2.Rproj
new file mode 100644
index 00000000000..8e3c2ebc99e
--- /dev/null
+++ b/ProgrammingAssignment2.Rproj
@@ -0,0 +1,13 @@
+Version: 1.0
+
+RestoreWorkspace: Default
+SaveWorkspace: Default
+AlwaysSaveHistory: Default
+
+EnableCodeIndexing: Yes
+UseSpacesForTab: Yes
+NumSpacesForTab: 2
+Encoding: UTF-8
+
+RnwWeave: Sweave
+LaTeX: pdfLaTeX
diff --git a/cachematrix.R b/cachematrix.R
index a50be65aa44..e008ffd56ad 100644
--- a/cachematrix.R
+++ b/cachematrix.R
@@ -1,15 +1,73 @@
-## Put comments here that give an overall description of what your
-## functions do
-
-## Write a short comment describing this function
+## library to provide matrix inversion caching
+## 
+## software provides two functions to be used in concert for the purposes
+## of wrapping a matrix object with an adaptor that memoizes inversion calls.
+##
+## uses: to be used in cases where a large matrix must be inverted multiple times,
+##       or if the inversion happens inside of a loop
+##
 
+## makeCacheMatrix
+## 
+## Description
+## Wraps a matrix object in a list with getter/setters for matrix inversion. this
+## function should be called when preparing a matrix for use with the cacheSolve 
+## function.
+##
+## Usage
+## tt <- matrix( rnorm(3000*3000,mean=0,sd=1), 3000, 3000)
+## cachingMatrix <- makeCacheMatrix(tt)
+##
+## Arguments
+## 
+## x     the matrix to be prepared for cached matrix inversion
+##
+## Returns
+##
+## a list with the keys set, get, setsolve, and getsolve
 makeCacheMatrix <- function(x = matrix()) {
-
+  m <- NULL
+  set <- function(y) {
+    x <<- y
+    m <<- NULL
+  }
+  get <- function() x
+  setsolve <- function(solve) m <<- solve
+  getsolve <- function() m
+  list(set = set, get = get,
+       setsolve = setsolve,
+       getsolve = getsolve) 
 }
 
 
-## Write a short comment describing this function
-
+## cacheSolve
+## 
+## Description
+## When provided a matrix prepared by makeCacheMatrix, calls
+## the native solve function to execute matrix inversion. If
+## the matrix is inverted again, a memoized result is provided
+## thereby accelerating response time.
+##
+##
+## Usage
+## tt <- matrix( rnorm(3000*3000,mean=0,sd=1), 3000, 3000)
+## cachingMatrix <- makeCacheMatrix(tt)
+## inverseOfMatrix <- cacheSolve(cachingMatrix) 
+##
+## Arguments
+## 
+## x     the object provided by makeCacheMatrix
+##
+## Returns
+##
+## the inverse of the original matrix, back in a native R matrix
 cacheSolve <- function(x, ...) {
-        ## Return a matrix that is the inverse of 'x'
+  m <- x$getsolve()
+  if(!is.null(m)) {
+    return(m)
+  }
+  data <- x$get()
+  m <- solve(data, ...)
+  x$setsolve(m)
+  m
 }