doc fixes

doc.go

@@ -22,27 +22,83 @@
 // WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 /*
-Package goquery implements features similar to jQuery, including the chainable syntax,
+Package goquery implements features similar to jQuery, including the chainable
-to manipulate and query an HTML document.
+syntax, to manipulate and query an HTML document.
 
-It depends on Go's experimental html package, which must be installed so that it can be imported
+It depends on Go's experimental html package, which must be installed so that it
-as "exp/html". See this tutorial on how to install it accordingly: http://code.google.com/p/go-wiki/wiki/InstallingExp
+can be imported as "exp/html". See this tutorial on how to install it 
+accordingly: http://code.google.com/p/go-wiki/wiki/InstallingExp
 
-It uses Cascadia as CSS selector (similar to Sizzle for jQuery). This dependency is automatically installed
+It uses Cascadia as CSS selector (similar to Sizzle for jQuery). This dependency
-when using "go get ..." to install GoQuery.
+is automatically installed when using "go get ..." to install GoQuery.
 
-To provide chainable interface, error management is strict, and goquery panics if an invalid Cascadia selector
+To provide a chainable interface, error management is strict, and goquery panics
-is used (basically the same behavior as jQuery/Sizzle/document.querySelectorAll, an error is thrown). This is
+if an invalid Cascadia selector is used (this is consistent with the behavior of
-necessary since multiple return values cannot be used to allow a chainable interface.
+jQuery/Sizzle/document.querySelectorAll, where an error is thrown). This is
+necessary since multiple return values cannot be used to allow a chainable 
+interface.
 
-It is hosted here, along with additional documentation in the README.md file:
+It is hosted on GitHub, along with additional documentation in the README.md
-https://github.com/puerkitobio/goquery
+file: https://github.com/puerkitobio/goquery
+
+The various methods are split into files based on the category of behavior:
+
+* array.go : array-like positional manipulation of the selection.
+    - First()
+    - Last()
+    - Eq()
+    - Get()
+    - Index...()
+    - Slice()
+
+* filter.go : filtering methods, that reduce the selection's set.
+    - Filter...()
+    - Not...()
+    - Has...()
+    - End()
+    - Intersection(), which is an alias of FilterSelection()
+
+* expand.go : methods that expand or augment the selection's set.
+    - Add...()
+    - AndSelf()
+    - Union(), which is an alias for AddSelection()
+
+* query.go : methods that query, or reflect, a node's identity.
+    - Contains()
+    - HasClass()
+    - Is...()
+
+* property.go : methods that inspect and get the node's properties values.
+    - Attr()
+    - Contents()
+    - Html()
+    - Length()
+    - Size(), which is an alias for Length()
+    - Text()
+    - Val()
+
+* traversal.go : methods to traverse the HTML document tree.
+    - Children...()
+    - Closest()
+    - Find...()
+    - Next...()
+    - Parent[s]...()
+    - Prev...()
+    - Siblings...()
+
+* iteration.go : methods to loop over the selection's nodes.
+    - Each()
+    - Map()
+
+* type.go : definition of the types exposed by GoQuery.
+    - Document
+    - Selection
 */
 package goquery
 
 // DONE array.go : Positional Manipulation: First(), Last(), Eq(), Get(), Index(), Slice()
 // DONE filter.go : Filtering: Filter(), Not(), Has(), End()
-// expand.go : "Expanding": Add(), AndSelf()
+// DONE expand.go : "Expanding": Add(), AndSelf()
 // query.go : Reflect (query) node: Is(), Contains(), HasClass()
 // property.go : Inspect node: Contents(), Html(), Text(), Attr(), Val(), Length(), Size()
 // traversal.go : Traversal: Find(), Children(), Parents...(), Next...(), Prev...(), Closest(), Siblings()
@@ -54,42 +110,42 @@ package goquery
 // TODO : Check each method, if it applies to any node or only Element nodes (Cascadia's selectors already make sure of that)
 
 // TODO : Add the following methods:
-// x Add() - Misc. Traversing
+// x Add()
-// - AndSelf() - Misc. Traversing
+// x AndSelf()
-// x Attr() - Attributes
+// x Attr()
-// x Children() - Tree Traversal
+// x Children()
 // - Closest() - Tree Traversal
-// x Contains() (static function?) - Utilities - needs tests
+// x Contains()
 // - Contents() (similar to Children(), but includes text and comment nodes, so Children() should filter them out) - Misc. Traversing
-// x Each() - Traversing
+// x Each()
-// x End() - Misc. Traversing
+// x End()
-// x Eq() - Filtering
+// x Eq()
-// x Filter() - Filtering
+// x Filter()
-// x Find() : Complete with Selection object and Node object as selectors - Tree Traversal
+// - Find() : Complete with Selection object and Node object as selectors - Tree Traversal
-// x First() - Filtering
+// x First()
-// x Get() - Node (DOM) Manipulation
+// x Get()
-// x Has() - Filtering
+// x Has()
-// x HasClass() - Attributes
+// x HasClass()
 // - Html() ? - Attributes
-// x Index() - DOM Manipulation
+// x Index()
 // - Is() - Filtering
-// x Last() - Filtering
+// x Last()
-// x Length() / Size() - jQUery property
+// x Length() / Size()
-// x Map() - Filtering
+// x Map()
 // - Next() - Tree traversal
 // - NextAll() - Tree traversal
 // - NextUntil() - Tree traversal
-// x Not() - Filtering
+// x Not()
 // - Parent() - Tree traversal
 // - Parents() - Tree traversal
 // - ParentsUntil() - Tree traversal
 // - Prev() - Tree traversal
 // - PrevAll() - Tree traversal
 // - PrevUntil() - Tree traversal
-// x PushStack() ? - Internals
+// x PushStack()
 // - Siblings() - Tree traversal
-// x Slice() - Filtering
+// x Slice()
 // - Text() - DOM Manipulation
-// x ToArray() Is not implemented, is Selection.Nodes
+// x ToArray()
-// x Unique() ? Or internally only, to remove duplicates and maintain node order? - Utilities
+// x Unique() internally only
 // - Val() ? - Attributes

expand.go

@@ -21,6 +21,11 @@ func (this *Selection) AddSelection(sel *Selection) *Selection {
 	return this.AddNodes(sel.Nodes...)
 }
 
+// Union() is an alias for AddSelection().
+func (this *Selection) Union(sel *Selection) *Selection {
+	return this.AddSelection(sel)
+}
+
 // AddNodes() adds the specified nodes to those in the
 // current selection and returns a new Selection object.
 func (this *Selection) AddNodes(nodes ...*html.Node) *Selection {

filter.go

@@ -61,8 +61,8 @@ func (this *Selection) NotSelection(s *Selection) *Selection {
 	return pushStack(this, winnowNodes(this, s.Nodes, false))
 }
 
-// Union() is an alias for FilterSelection().
+// Intersection() is an alias for FilterSelection().
-func (this *Selection) Union(s *Selection) *Selection {
+func (this *Selection) Intersection(s *Selection) *Selection {
 	return this.FilterSelection(s)
 }
 

filter_test.go

@@ -94,9 +94,9 @@ func TestNotSelection(t *testing.T) {
 	}
 }
 
-func TestUnion(t *testing.T) {
+func TestIntersection(t *testing.T) {
 	sel := Doc().Find(".pvk-gutter")
-	sel2 := Doc().Find("div").Union(sel)
+	sel2 := Doc().Find("div").Intersection(sel)
 	if len(sel2.Nodes) != 6 {
 		t.Errorf("Expected 6 nodes, found %v.", len(sel2.Nodes))
 	}

property.go

@@ -4,8 +4,9 @@ import (
 	"exp/html"
 )
 
-// Attr() gets the specified attribute's value for the first element in the Selection.
+// Attr() gets the specified attribute's value for the first element in the
-// To get the value for each element individually, use a looping construct such as Each() or Map() method.
+// Selection. To get the value for each element individually, use a looping
+// construct such as Each() or Map() method.
 func (this *Selection) Attr(attrName string) (val string, exists bool) {
 	if len(this.Nodes) == 0 {
 		return