improve documentation (issue 181)

bitset.go

@@ -145,7 +145,10 @@ func wordsIndex(i uint) uint {
 	return i & (wordSize - 1)
 }
 
-// New creates a new BitSet with a hint that length bits will be required
+// New creates a new BitSet with a hint that length bits will be required.
+// The memory usage is at least length/8 bytes.
+// In case of allocation failure, the function will return a BitSet with zero
+// capacity.
 func New(length uint) (bset *BitSet) {
 	defer func() {
 		if r := recover(); r != nil {
@@ -627,7 +630,8 @@ func (b *BitSet) wordCount() int {
 	return wordsNeededUnbound(b.length)
 }
 
-// Clone this BitSet
+// Clone this BitSet, returning a new BitSet that has the same bits set.
+// In case of allocation failure, the function will return an empty BitSet.
 func (b *BitSet) Clone() *BitSet {
 	c := New(b.length)
 	if b.set != nil { // Clone should not modify current object
@@ -785,6 +789,7 @@ func sortByLength(a *BitSet, b *BitSet) (ap *BitSet, bp *BitSet) {
 
 // Intersection of base set and other set
 // This is the BitSet equivalent of & (and)
+// In case of allocation failure, the function will return an empty BitSet.
 func (b *BitSet) Intersection(compare *BitSet) (result *BitSet) {
 	panicIfNull(b)
 	panicIfNull(compare)
@@ -959,6 +964,7 @@ func (b *BitSet) cleanLastWord() {
 }
 
 // Complement computes the (local) complement of a bitset (up to length bits)
+// In case of allocation failure, the function will return an empty BitSet.
 func (b *BitSet) Complement() (result *BitSet) {
 	panicIfNull(b)
 	result = New(b.length)