Edited comments, adding computation message

KingCode · KingCode · commit e8848939c7fc · 2015-01-19T15:33:53.000-05:00
diff --git a/cachematrix.R b/cachematrix.R
@@ -1,20 +1,35 @@
-## Put comments here that give an overall description of what your
-## functions do
+## A pair of functions which implement the encapsulation and caching of a matrix
+## and its inverse's computation.   
+## 
+## makeCacheMatrix is a factory function yielding an object providing access methods to 
+## retrieve and assign the matrix and its inverse. 
+## 
+## cacheSolve takes an object obtained via makeCacheMatrix and returns the inverse if already computed;
+## otherwise the inverse is computed and cached by invoking setinv() on its argument prior to being 
+## returned.
+##
+## It is important to note that the two functions are designed to be used together to reap the 
+## caching benefit: 
+##      my_matrix <- makeCacheMatrix( matrix( <values>, <dimensions>)
+##      cacheSolve( my_matrix)
+##      my_matrix$getinv()
+##
+## Some care must be taken to invoke cacheSolve if changing the matrix value via set, prior to
+## invoking getinv.
+##
 
 ## A factory function which yields an object encapsulating a square invertible matrix x,
 ## with the following methods:
 ##
 ##   get(), retrieves the current matrix; set( m) where m is assumed to be a square matrix;
 ##   getinv(), retrieves the inversion of x, or NULL if it has not been set.
 ##   setinv( inv) which assigns inv to the value returned by getinv(), but only if getinv() is NULL
-##   set( new_x), sets the square invertible matrix to be new_x, unless x is already assigned, 
-##   in which case nothing is done. 
+##   set( new_x), assigns new_x to be the new matrix value, and ensures that if getinv() is the next
+##   method invoked, NULL will be returned - see usage pattern at the top.
+##
+## If provided, x is assumed to be a square invertible matrix. Otherwise the default is a 1 by 1 empty matrix.
 ##
-## If provided, x is assumed to be a square invertible matrix and can't be changed in the returned object. 
-## Otherwise the default is a 1 by 1 empty matrix which can be overwritten by invoking set().
-## Note that the matrix inversion computation is not itself provided, only its storage. Therefore, 
-## one should check for getinv() yielding NULL before using its value, and/or assign the inverse by calling
-## x$setinv.
+## Note that the matrix inversion computation is not itself provided, only its storage. See usage pattern above. 
 
 makeCacheMatrix <- function(x = matrix()) {
     i <- NULL # the inverse of x
@@ -36,8 +51,9 @@ makeCacheMatrix <- function(x = matrix()) {
 }
 
 
-## Yields the inverse of the x$get(), computing it if necessary. In both cases, the inverse will 
-## be returned by future invocations of  x$getinv().
+## Yields the inverse of the x$get(), computing it only if necessary. 
+## If computed, the result is cached, i.e. future invocations of  x$getinv() will return
+## the same value without computation until the next invocation of  x$set.
 
 cacheSolve <- function(x, ...) {
 
@@ -46,6 +62,7 @@ cacheSolve <- function(x, ...) {
         if( !is.null( cached))
             return( cached) 
 
+        message( "Computing inverse");
         ## Cache the result and yield
         x$setinv( solve(x$get(), ...))
         x$getinv()
