[PATCH] some documentation love

[Federico G. Schwindt]

Ops, you can ignore the vcl.rst change (first chunk).  That's part of another diff I sent previously.

On Thu, 23 Feb 2012 15:39:18 +0000
"Federico G. Schwindt" <fgsch at lodoss.net> wrote:

> Minor touches:
> 
> - mention vmod_std(7)
> - HEADER is released and used by vmod_std(7) so put it in its own line.
>   The explanation is still needed though.
> - for consistency replace leading tabs with spaces 
> - *fallback* are not strings so avoid mentioning the type
> - use ascii characters in vmod_std(7)
> 
> OK?
> 
> diff --git a/doc/sphinx/reference/vcl.rst b/doc/sphinx/reference/vcl.rst
> index 9e71fbd..43197f6 100644
> --- a/doc/sphinx/reference/vcl.rst
> +++ b/doc/sphinx/reference/vcl.rst
> @@ -275,6 +275,17 @@ An example of a fallback director::
>                           // are unhealthy.
>    }
>  
> +The least-connection director
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +The least-connection director will pick a backend with the least number of
> +established connections.
> +
> +Each backend requires a .weight option which sets the amount of traffic
> +each backend will get compared to the others. Equal weight means equal
> +traffic. A backend with lower weight than an other will get proportionally
> +less traffic.
> +
>  Backend probes
>  --------------
>  
> diff --git a/doc/sphinx/reference/vmod.rst b/doc/sphinx/reference/vmod.rst
> index 57163c5..a76dee1 100644
> --- a/doc/sphinx/reference/vmod.rst
> +++ b/doc/sphinx/reference/vmod.rst
> @@ -22,7 +22,7 @@ For instance::
>  The "std" vmod is one you get with Varnish, it will always be there
>  and we will put "boutique" functions in it, such as the "toupper"
>  function shown above.  The full contents of the "std" module is
> -documented in XXX:TBW.
> +documented in vmod_std(7).
>  
>  This part of the manual is about how you go about writing your own
>  VMOD, how the language interface between C and VCC works etc.  This
> @@ -185,7 +185,12 @@ VOID
>  	Can only be used for return-value, which makes the function a VCL
>  	procedure.
>  
> -IP, BOOL, HEADER
> +HEADER
> +	C-type: ``enum gethdr_e, const char *``
> +
> +	XXX: explain me
> +
> +IP, BOOL
>  	XXX: these types are not released for use in vmods yet.
>  
>  
> diff --git a/doc/sphinx/reference/vmod_std.rst b/doc/sphinx/reference/vmod_std.rst
> index 1ea8193..f1a8ba2 100644
> --- a/doc/sphinx/reference/vmod_std.rst
> +++ b/doc/sphinx/reference/vmod_std.rst
> @@ -33,7 +33,7 @@ toupper
>  Prototype
>  	toupper(STRING S)
>  Return value
> -       String
> +	String
>  Description
>  	Converts the STRING S to upper case.
>  Example
> @@ -44,18 +44,18 @@ tolower
>  Prototype
>  	tolower(STRING S)
>  Return value
> -       String
> +	String
>  Description
>  	Converts the STRING to lower case.
>  Example
> -        set beresp.http.x-nice = std.tolower("VerY");
> +	set beresp.http.x-nice = std.tolower("VerY");
>  
>  set_up_tos
>  ----------
>  Prototype
>  	set_ip_tos(INT I)
>  Return value
> -       Void
> +	Void
>  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
> @@ -71,7 +71,7 @@ random
>  Prototype
>  	random(REAL a, REAL b)
>  Return value
> -       Real
> +	Real
>  Description
>  	Returns a random REAL number between *a* and *b*.
>  Example
> @@ -82,7 +82,7 @@ log
>  Prototype
>  	log(STRING string)
>  Return value
> -       Void
> +	Void
>  Description
>  	Logs string to the shared memory log.
>  Example
> @@ -93,7 +93,7 @@ syslog
>  Prototype
>  	syslog(INT priority, STRING string)
>  Return value
> -        Void
> +	Void
>  Description
>  	Logs *string* to syslog marked with *priority*.
>  Example
> @@ -104,7 +104,7 @@ fileread
>  Prototype
>  	fileread(STRING filename)
>  Return value
> -        String
> +	String
>  Description
>  	Reads a file and returns a string with the content. Please
>  	note that it is not recommended to send variables to this
> @@ -118,12 +118,11 @@ duration
>  Prototype
>  	duration(STRING s, DURATION fallback)
>  Return value
> -       Duration
> +	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 it fails to parse the string *fallback* 
> -	will be used
> +	(weeks) units. If it fails to parse *fallback* will be used
>  Example
>  	set beresp.ttl = std.duration("1w", 3600);
>  
> @@ -132,19 +131,19 @@ integer
>  Prototype
>  	integer(STRING s, INT fallback)
>  Return value
> -       Int
> +	Int
>  Description
> -	Converts the string s to an integer.  If it fails to parse the
> -	string *fallback* will be used
> +	Converts the string s to an integer.  If it fails to parse
> +	*fallback* will be used
>  Example
> -	if (std.integer(beresp.http.x-foo, 0) > 5) { … }
> +	if (std.integer(beresp.http.x-foo, 0) > 5) { ... }
>  
>  collect
>  -------
>  Prototype
>  	collect(HEADER header)
>  Return value
> -       Void
> +	Void
>  Description
>  	Collapses the header, joining the headers into one.
>  Example