From 505516529b0f2c3d99f132a45666c2a424cb3ce0 Mon Sep 17 00:00:00 2001
From: Martin Angers <martin.n.angers@gmail.com>
Date: Sat, 1 Sep 2012 11:03:02 -0400
Subject: [PATCH] finalize type.go documentation

---
 doc.go  |  2 +-
 type.go | 16 ++++++++++++++++
 2 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/doc.go b/doc.go
index 7e0f67c..bd4117d 100644
--- a/doc.go
+++ b/doc.go
@@ -103,7 +103,7 @@ package goquery
 // property.go : Inspect node: Contents(), Html(), Text(), Attr(), ** Does it make sense in a static HTML tree? Val()**, Length(), Size()
 // traversal.go : Traversal: Find(), Children(), Parents...(), Next...(), Prev...(), Closest(), Siblings()
 // DONE iteration.go : Iteration: Each(), Map()
-// type.go : Selection and Document
+// DONE type.go : Selection and Document
 
 // TODO : Benchmarks
 
diff --git a/type.go b/type.go
index e073c23..5d74f72 100644
--- a/type.go
+++ b/type.go
@@ -6,17 +6,27 @@ import (
 	"net/url"
 )
 
+// Document represents an HTML document to be manipulated. Unlike jQuery, which
+// is loaded as part of a DOM document, and thus acts upon its containing
+// document, GoQuery doesn't know which HTML document to act upon. So it needs
+// to be told, and that's what the Document class is for. It holds the root
+// document node to manipulate, and can make selections on this document.
 type Document struct {
 	Root *html.Node
 	Url  *url.URL
 }
 
+// NewDocumentFromNode() is a Document constructor that takes a root html Node
+// as argument.
 func NewDocumentFromNode(root *html.Node) (d *Document) {
 	// Create and fill the document
 	d = &Document{root, nil}
 	return
 }
 
+// NewDocument() is a Document constructor that takes a string URL as argument.
+// It loads the specified document, parses it, and stores the root Document
+// node, ready to be manipulated.
 func NewDocument(url string) (d *Document, e error) {
 	// Load the URL
 	res, e := http.Get(url)
@@ -36,12 +46,18 @@ func NewDocument(url string) (d *Document, e error) {
 	return
 }
 
+// Selection represents a collection of nodes matching some criteria. The
+// initial Selection can be created by using Document.Find(), and then
+// manipulated using the jQuery-like chainable syntax and methods.
 type Selection struct {
 	Nodes    []*html.Node
 	document *Document
 	prevSel  *Selection
 }
 
+// TODO : Keep those methods? When using pushStack, this should not be necessary,
+// but maybe yes when iterating with Each or Map?
+
 func newEmptySelection(doc *Document) *Selection {
 	return &Selection{nil, doc, nil}
 }