[tor-commits] [goptlib/master] Sexy godoc output.

[dcf at torproject.org]

commit 86cdde20fe2830e2d0ea6a1f21d494fbc2a2078c
Author: David Fifield <david at bamsoftware.com>
Date:   Mon Nov 25 21:41:43 2013 -0800

    Sexy godoc output.
---
 examples/dummy-client/dummy-client.go |   13 +++---
 examples/dummy-server/dummy-server.go |   15 ++++---
 pt.go                                 |   79 +++++++++++++++++----------------
 socks/socks.go                        |   21 ++++++++-
 4 files changed, 78 insertions(+), 50 deletions(-)

diff --git a/examples/dummy-client/dummy-client.go b/examples/dummy-client/dummy-client.go
index 5d96549..783788a 100644
--- a/examples/dummy-client/dummy-client.go
+++ b/examples/dummy-client/dummy-client.go
@@ -1,10 +1,13 @@
+// Dummy no-op pluggable transport client. Works only as a managed proxy.
+//
 // Usage (in torrc):
-//   UseBridges 1
-//   Bridge dummy X.X.X.X:YYYY
-//   ClientTransportPlugin dummy exec dummy-client
+// 	UseBridges 1
+// 	Bridge dummy X.X.X.X:YYYY
+// 	ClientTransportPlugin dummy exec dummy-client
+//
 // Because this transport doesn't do anything to the traffic, you can use any
-// ordinary relay's ORPort in the Bridge line.
-
+// ordinary relay's ORPort in the Bridge line; it doesn't have to declare
+// support for the dummy transport.
 package main
 
 import (
diff --git a/examples/dummy-server/dummy-server.go b/examples/dummy-server/dummy-server.go
index 599a5bf..86176d7 100644
--- a/examples/dummy-server/dummy-server.go
+++ b/examples/dummy-server/dummy-server.go
@@ -1,9 +1,14 @@
+// Dummy no-op pluggable transport server. Works only as a managed proxy.
+//
 // Usage (in torrc):
-//   BridgeRelay 1
-//   ORPort 9001
-//   ExtORPort 6669
-//   ServerTransportPlugin dummy exec dummy-server
-
+// 	BridgeRelay 1
+// 	ORPort 9001
+// 	ExtORPort 6669
+// 	ServerTransportPlugin dummy exec dummy-server
+//
+// Because the dummy transport doesn't do anything to the traffic, you can
+// connect to it with any ordinary Tor client; you don't have to use
+// dummy-client.
 package main
 
 import (
diff --git a/pt.go b/pt.go
index 03c2314..eb7048b 100644
--- a/pt.go
+++ b/pt.go
@@ -1,50 +1,53 @@
-// Tor pluggable transports library.
+// Package pt implements the Tor pluggable transports specification.
 //
 // Sample client usage:
-//
-// import "git.torproject.org/pluggable-transports/goptlib.git"
-// var ptInfo pt.ClientInfo
-// var err error
-// ptInfo, err := pt.ClientSetup([]string{"foo"})
-// if err != nil {
-// 	os.Exit(1)
-// }
-// for _, methodName := range ptInfo.MethodNames {
-// 	ln, err := startSocksListener()
+// 	var ptInfo pt.ClientInfo
+// 	var err error
+// 	ptInfo, err = pt.ClientSetup([]string{"foo"})
 // 	if err != nil {
-// 		pt.CmethodError(methodName, err.Error())
-// 		continue
+// 		os.Exit(1)
+// 	}
+// 	for _, methodName := range ptInfo.MethodNames {
+// 		ln, err := startSocksListener()
+// 		if err != nil {
+// 			pt.CmethodError(methodName, err.Error())
+// 			continue
+// 		}
+// 		pt.Cmethod(methodName, "socks4", ln.Addr())
 // 	}
-// 	pt.Cmethod(methodName, "socks4", ln.Addr())
-// }
-// pt.CmethodsDone()
+// 	pt.CmethodsDone()
+// See the socks package for help with writing a SOCKS listener.
 //
 // Sample server usage:
-//
-// import "git.torproject.org/pluggable-transports/goptlib.git"
-// var ptInfo pt.ServerInfo
-// var err error
-// ptInfo, err = pt.ServerSetup([]string{"foo", "bar"})
-// if err != nil {
-// 	os.Exit(1)
-// }
-// for _, bindaddr := range ptInfo.Bindaddrs {
-// 	ln, err := startListener(bindaddr.Addr, bindaddr.MethodName)
-// 	if err != nil {
-// 		pt.SmethodError(bindaddr.MethodName, err.Error())
-// 		continue
+// 	func handler(conn net.Conn) {
+// 		or, err := pt.ConnectOr(&ptInfo, conn, "foo")
+// 		if err != nil {
+// 			return
+// 		}
+// 		// do something with or and conn
 // 	}
-// 	pt.Smethod(bindaddr.MethodName, ln.Addr())
-// }
-// pt.SmethodsDone()
-// func handler(conn net.Conn, methodName string) {
-// 	or, err := pt.ConnectOr(&ptInfo, conn, methodName)
+// 	...
+// 	var ptInfo pt.ServerInfo
+// 	var err error
+// 	ptInfo, err = pt.ServerSetup([]string{"foo"})
 // 	if err != nil {
-// 		return
+//	 	os.Exit(1)
 // 	}
-// 	// Do something with or and conn.
-// }
-
+// 	for _, bindaddr := range ptInfo.Bindaddrs {
+// 		ln, err := startListener(bindaddr.Addr, bindaddr.MethodName)
+// 		if err != nil {
+// 			pt.SmethodError(bindaddr.MethodName, err.Error())
+// 			continue
+// 		}
+// 		pt.Smethod(bindaddr.MethodName, ln.Addr())
+// 	}
+// 	pt.SmethodsDone()
+//
+// Tor pluggable transports specification:
+// https://gitweb.torproject.org/torspec.git/blob/HEAD:/pt-spec.txt.
+//
+// Extended ORPort Authentication:
+// https://gitweb.torproject.org/torspec.git/blob/HEAD:/proposals/217-ext-orport-auth.txt.
 package pt
 
 import (
diff --git a/socks/socks.go b/socks/socks.go
index 788d53c..b82fba7 100644
--- a/socks/socks.go
+++ b/socks/socks.go
@@ -1,5 +1,7 @@
-// SOCKS4a server library.
-
+// Package socks implements a SOCKS4a server sufficient for a Tor client
+// transport plugin.
+//
+// http://ftp.icm.edu.pl/packages/socks/socks4/SOCKS4.protocol
 package socks
 
 import (
@@ -22,6 +24,21 @@ const (
 // requested destination string. If the callback returns an error, sends a SOCKS
 // request failed message. Otherwise, sends a SOCKS request granted message for
 // the destination address returned by the callback.
+// 	var remote net.Conn
+// 	err := socks.AwaitSocks4aConnect(local.(*net.TCPConn), func(dest string) (*net.TCPAddr, error) {
+// 		var err error
+// 		// set remote in outer function environment
+// 		remote, err = net.Dial("tcp", dest)
+// 		if err != nil {
+// 			return nil, err
+// 		}
+// 		return remote.RemoteAddr().(*net.TCPAddr), nil
+// 	})
+// 	if err != nil {
+// 		return err
+// 	}
+// 	defer remote.Close()
+// 	copyLoop(local, remote)
 func AwaitSocks4aConnect(conn *net.TCPConn, connect func(string) (*net.TCPAddr, error)) error {
 	dest, err := readSocks4aConnect(conn)
 	if err != nil {