diff --git a/cachematrix.R b/cachematrix.R
index a50be65aa44..462ed40c923 100644
--- a/cachematrix.R
+++ b/cachematrix.R
@@ -1,15 +1,42 @@
-## Put comments here that give an overall description of what your
-## functions do
-
-## Write a short comment describing this function
+## Pair of functions that cache the inverse of a matrix
+## Usage: Pass the result of a makeCacheMatrix call to cacheSolve 
 
+#' Util function that set the matrix and the inverse in an environment
+#' @param x an invertible matrix
+#' examples
+#' x = makeCacheMatrix(matrix(rnorm(9), 3, 3))
+#' x$set(matrix(rnorm(16), 4, 4))
 makeCacheMatrix <- function(x = matrix()) {
-
+  # todo error if x is not a matrix
+  inv <- NULL
+  set <- function(y) {
+    x <<- y
+    inv <<- NULL
+  }
+  get <- function() x
+  setinverse <- function(inverse) inv <<- inverse
+  getinverse <- function() inv
+  list(set = set, get = get,
+       setinverse = setinverse,
+       getinverse = getinverse)
 }
 
 
-## Write a short comment describing this function
-
+#' Compute and cache the inverse of a matrix
+#' @param x the result of a previous makeCacheMatrix call
+#' @param ... additional arguments to pass to solve function
+#' examples
+#' x = makeCacheMatrix(matrix(rnorm(9), 3, 3))
+#' cacheSolve(x)
 cacheSolve <- function(x, ...) {
-        ## Return a matrix that is the inverse of 'x'
+  ## Return a matrix that is the inverse of 'x'
+  inv <- x$getinverse()
+  if(!is.null(inv)) {
+    message("getting cached matrix inverse")
+    return(inv)
+  }
+  data <- x$get()
+  inv <- solve(data, ...)
+  x$setinverse(inv)
+  inv
 }