add more examples to README and doc.go.

README.md

@@ -56,6 +56,29 @@ See it in action:
   * Every assert func takes the `testing.T` object as the first argument.  This is how it writes the errors out through the normal `go test` capabilities.
   * Every assert func returns a bool indicating whether the assertion was successful or not, this is useful for if you want to go on making further assertions under certain conditions.
 
+if you assert many times, use the below:
+
+    func TestSomething(t *testing.T) {
+      assert := assert.New(t)
+      
+      // assert equality
+      assert.Equal(123, 123, "they should be equal")
+
+      // assert inequality
+      assert.NotEqual(123, 456, "they should not be equal")
+
+      // assert for nil (good for errors)
+      assert.Nil(object)
+
+      // assert for not nil (good when you expect something)
+      if assert.NotNil(object) {
+
+      	// now we know that object isn't nil, we are safe to make
+      	// further assertions without causing any errors
+        assert.Equal("Something", object.Value)
+      }
+    }
+
 `http` package
 --------------
 
@@ -167,6 +190,39 @@ For a more complete example, using all of the functionality provided by the suit
 
 For more information on writing suites, check out the [API documentation for the `suite` package](http://go.pkgdoc.org/github.com/stretchr/testify/suite).
 
+`Suite` object has assertion methods:
+
+    // Basic imports
+    import (
+        "testing"
+        "github.com/stretchr/testify/suite"
+    )
+
+    // Define the suite, and absorb the built-in basic suite
+    // functionality from testify - including assertion methods.
+    type ExampleTestSuite struct {
+        suite.Suite
+        VariableThatShouldStartAtFive int
+    }
+
+    // Make sure that VariableThatShouldStartAtFive is set to five
+    // before each test
+    func (suite *ExampleTestSuite) SetupTest() {
+        suite.VariableThatShouldStartAtFive = 5
+    }
+
+    // All methods that begin with "Test" are run as tests within a
+    // suite.
+    func (suite *ExampleTestSuite) TestExample() {
+        suite.Equal(suite.VariableThatShouldStartAtFive, 5)
+    }
+
+    // In order for 'go test' to run this suite, we need to create
+    // a normal test function and pass our suite to suite.Run
+    func TestExampleTestSuite(t *testing.T) {
+        suite.Run(t, new(ExampleTestSuite))
+    }
+
 ------
 
 Installation

assert/doc.go

@@ -17,6 +17,22 @@
 //
 //    }
 //
+// if you assert many times, use the below:
+//
+//    import (
+//      "testing"
+//      "github.com/stretchr/testify/assert"
+//    )
+//
+//    func TestSomething(t *testing.T) {
+//      assert := assert.New(t)
+//
+//      var a string = "Hello"
+//      var b string = "Hello"
+//
+//      assert.Equal(a, b, "The two words should be the same.")
+//    }
+//
 // Assertions
 //
 // Assertions allow you to easily write test code, and are global funcs in the `assert` package.
@@ -70,5 +86,49 @@
 //    } [, message [, format-args]])
 //
 //    assert.WithinDuration(t, timeA, timeB, deltaTime, [, message [, format-args]])
-
+//
+// assert package contains Assertions object. it has assertion methods.
+//
+// Here is an overview of the assert functions:
+//    assert.Equal(expected, actual [, message [, format-args])
+//
+//    assert.NotEqual(notExpected, actual [, message [, format-args]])
+//
+//    assert.True(actualBool [, message [, format-args]])
+//
+//    assert.False(actualBool [, message [, format-args]])
+//
+//    assert.Nil(actualObject [, message [, format-args]])
+//
+//    assert.NotNil(actualObject [, message [, format-args]])
+//
+//    assert.Empty(actualObject [, message [, format-args]])
+//
+//    assert.NotEmpty(actualObject [, message [, format-args]])
+//
+//    assert.Error(errorObject [, message [, format-args]])
+//
+//    assert.NoError(errorObject [, message [, format-args]])
+//
+//    assert.Implements((*MyInterface)(nil), new(MyObject) [,message [, format-args]])
+//
+//    assert.IsType(expectedObject, actualObject [, message [, format-args]])
+//
+//    assert.Contains(string, substring [, message [, format-args]])
+//
+//    assert.NotContains(string, substring [, message [, format-args]])
+//
+//    assert.Panics(func(){
+//
+//	    // call code that should panic
+//
+//    } [, message [, format-args]])
+//
+//    assert.NotPanics(func(){
+//
+//	    // call code that should not panic
+//
+//    } [, message [, format-args]])
+//
+//    assert.WithinDuration(timeA, timeB, deltaTime, [, message [, format-args]])
 package assert

suite/doc.go

@@ -23,6 +23,8 @@
 // identity that "go test" is already looking for (i.e.
 // func(*testing.T)).
 //
+// Suite object has assertion methods.
+//
 // A crude example:
 //     // Basic imports
 //     import (
@@ -49,6 +51,7 @@
 //     // suite.
 //     func (suite *ExampleTestSuite) TestExample() {
 //         assert.Equal(suite.T(), suite.VariableThatShouldStartAtFive, 5)
+//         suite.Equal(suite.VariableThatShouldStartAtFive, 5)
 //     }
 //
 //     // In order for 'go test' to run this suite, we need to create