Create .rst documentation from the vmod.vcc file.

This causes a change of syntax for the vcc file, it is however
very slight:  "Module", "Init", "Function", "Object" and "Method" needs
a "$" prefix, and the methods refer to the previous $Objecet without
the enclosing { }.

The first contiguous set of lines starting with "#" is treated as
a copyright notice, and emitted last, unless the first line is "#-"

lib/libvmod_debug/vmod.vcc

-#-
+#
 # Copyright (c) 2010-2013 Varnish Software AS
 # All rights reserved.
 #
@@ -25,15 +25,49 @@
 # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 # SUCH DAMAGE.
 
-Module debug
-Init init_function
-Function VOID panic(STRING_LIST)
-Function STRING author(ENUM { phk, des, kristian, mithrandir })
-Function VOID test_priv_call(PRIV_CALL)
-Function VOID test_priv_vcl(PRIV_VCL)
-Object obj(STRING) {
-	# NOTE: .enum before .foo as part of test r01332.vtc
-	Method VOID .enum(ENUM { phk, des, kristian, mithrandir, martin })
-	Method STRING .foo(STRING why)
-	Method TIME .date()
-}
+$Module debug Development, test and debug
+
+DESCRIPTION
+===========
+
+This vmod is used to develop, test and debug the various aspects
+of VMOD handling in Varnish.
+
+$Init init_function
+
+Call this whenever a VCL is loaded which imports this vmod.
+
+$Function VOID panic(STRING_LIST)
+
+Don't.
+
+$Function STRING author(ENUM { phk, des, kristian, mithrandir })
+
+Test function for ENUM arguments
+
+$Function VOID test_priv_call(PRIV_CALL)
+
+Test function for call private pointers
+
+$Function VOID test_priv_vcl(PRIV_VCL)
+
+Test function for VCL private pointers
+
+$Object obj(STRING) 
+
+Test object
+
+.. NOTE: .enum before .foo as part of test r01332.vtc
+$Method VOID .enum(ENUM { phk, des, kristian, mithrandir, martin })
+
+Testing that emums work as part of object and that the parser isn't
+(too) buggy.
+
+$Method STRING .foo(STRING why)
+
+Foo indeed.
+
+$Method TIME .date()
+
+You never know when you need a date.
+

lib/libvmod_directors/vmod.vcc

@@ -25,24 +25,20 @@
 # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 # SUCH DAMAGE.
 
-Module directors
+$Module directors Backend traffic directors
 
-Object round_robin() {
-	Method VOID .add_backend(BACKEND)
-	Method BACKEND .backend()
-}
+$Object round_robin()
+$Method VOID .add_backend(BACKEND)
+$Method BACKEND .backend()
 
-Object fallback() {
-	Method VOID .add_backend(BACKEND)
-	Method BACKEND .backend()
-}
+$Object fallback()
+$Method VOID .add_backend(BACKEND)
+$Method BACKEND .backend()
 
-Object random() {
-	Method VOID .add_backend(BACKEND, REAL)
-	Method BACKEND .backend()
-}
+$Object random()
+$Method VOID .add_backend(BACKEND, REAL)
+$Method BACKEND .backend()
 
-Object hash() {
-	Method VOID .add_backend(BACKEND, REAL)
-	Method BACKEND .backend(STRING_LIST)
-}
+$Object hash()
+$Method VOID .add_backend(BACKEND, REAL)
+$Method BACKEND .backend(STRING_LIST)

lib/libvmod_std/vmod.vcc

 #-
-# Copyright (c) 2010-2011 Varnish Software AS
+# Copyright (c) 2010-2013 Varnish Software AS
 # All rights reserved.
 #
 # Author: Poul-Henning Kamp <phk@FreeBSD.org>
@@ -25,17 +25,141 @@
 # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 # SUCH DAMAGE.
 
-Module std
-Function STRING toupper(STRING_LIST)
-Function STRING tolower(STRING_LIST)
-Function VOID set_ip_tos(INT)
-Function REAL random(REAL, REAL)
-Function VOID log(STRING_LIST)
-Function VOID syslog(INT, STRING_LIST)
-Function STRING fileread(PRIV_CALL, STRING)
-Function DURATION duration(STRING, DURATION)
-Function INT integer(STRING, INT)
-Function VOID collect(HEADER)
-Function IP ip(STRING, IP)
-Function BOOL healthy(BACKEND)
-Function INT port(IP)
+$Module std Varnish Standard Module
+
+DESCRIPTION
+===========
+
+Vmod_std contains basic functions which are part and parcel of Varnish,
+but which for reasons of architecture fit better in a VMOD.
+
+One particular class of functions in vmod_std is the conversions functions
+which all have the form::
+
+	TYPE type(STRING, TYPE)
+
+These functions attempt to convert STRING to the TYPE, and if that fails,
+they return the second argument, which must have the given TYPE.
+
+$Function STRING toupper(STRING_LIST)
+
+Description
+	Converts the string *s* to upper case.
+Example
+	set beresp.http.x-scream = std.toupper("yes!");
+
+$Function STRING tolower(STRING_LIST)
+
+Description
+	Converts the string *s* to lower case.
+Example
+	set beresp.http.x-nice = std.tolower("VerY");
+
+$Function VOID set_ip_tos(INT)
+
+Description
+	Sets the Type-of-Service flag for the current session. Please
+	note that the TOS flag is not removed by the end of the
+	request so probably want to set it on every request should you
+	utilize it.
+Example
+	| if (req.url ~ ^/slow/) {
+	|    std.set_ip_tos(0x0);
+	| }
+
+$Function REAL random(REAL, REAL)
+
+Description
+	Returns a random REAL number between *a* and *b*.
+Example
+	set beresp.http.x-random-number = std.random(1, 100);
+
+$Function VOID log(STRING_LIST)
+
+Description
+	Logs *string* to the shared memory log, using VSL tag *SLT_VCL_Log*.
+Example
+	std.log("Something fishy is going on with the vhost " + req.host);
+
+$Function VOID syslog(INT, STRING_LIST)
+
+Description
+	Logs *string* to syslog marked with *priority*.  See your
+	system's syslog.h file for the legal values of *priority*.
+Example
+	std.syslog(8 + 1, "Something is wrong");
+
+$Function STRING fileread(PRIV_CALL, STRING)
+
+Description
+	Reads a file and returns a string with the content. Please
+	note that it is not recommended to send variables to this
+	function the caching in the function doesn't take this into
+	account. Also, files are not re-read.
+Example
+	set beresp.http.x-served-by = std.fileread("/etc/hostname");
+
+$Function VOID collect(HEADER)
+
+Description
+	Collapses the header, joining the headers into one.
+Example
+	std.collect(req.http.cookie);
+	This will collapse several Cookie: headers into one, long
+	cookie header.
+
+$Function DURATION duration(STRING, DURATION)
+
+Description
+	Converts the string *s* to seconds. *s* can be quantified with
+	the usual s (seconds), m (minutes), h (hours), d (days) and w
+	(weeks) units. If *s* fails to parse, *fallback* will be returned.
+Example
+	set beresp.ttl = std.duration("1w", 3600s);
+
+$Function INT integer(STRING, INT)
+
+Description
+	Converts the string *s* to an integer.  If *s* fails to parse,
+	*fallback* will be returned.
+Example
+	if (std.integer(beresp.http.x-foo, 0) > 5) { ... }
+
+$Function IP ip(STRING, IP)
+
+Description
+	Converts string *s* to the first IP number returned by
+	the system library function getaddrinfo(3).  If conversion
+	fails, *fallback* will be returned.
+Example
+	if (std.ip(req.http.X-forwarded-for, "0.0.0.0") ~ my_acl) { ... }
+
+$Function BOOL healthy(BACKEND)
+
+Description
+	Returns true if the backend is healthy
+
+$Function INT port(IP)
+
+Description
+	Returns the port number of an IP address
+
+
+SEE ALSO
+========
+
+* vcl(7)
+* varnishd(1)
+
+HISTORY
+=======
+
+The Varnish standard module was released along with Varnish Cache 3.0.
+This manual page was written by Per Buer with help from Martin Blix
+Grydeland.
+
+COPYRIGHT
+=========
+
+This document is licensed under the same licence as Varnish
+itself. See LICENCE for details.