Fix various documentation errors

basis/io/directories/directories-docs.factor

@@ -6,7 +6,7 @@ HELP: cwd
 { $values { "path" "a pathname string" } }
 { $description "Outputs the current working directory of the Factor process." }
 { $errors "Windows CE has no concept of ``current directory'', so this word throws an error there." }
-{ $notes "User code should use " { $link with-directory } " or " { $link set-current-directory } " instead." } ;
+{ $notes "User code should use the value of the " { $link current-directory } " variable instead." } ;
 
 HELP: cd
 { $values { "path" "a pathname string" } }

basis/io/sockets/sockets-docs.factor

@@ -3,11 +3,20 @@ strings byte-arrays continuations destructors quotations ;
 IN: io.sockets
 
 ARTICLE: "network-addressing" "Address specifiers"
-"The networking words are quite general and work with " { $emphasis "address specifiers" } " rather than concrete concepts such as host names. There are four types of address specifiers:"
+"The networking words are quite general and work with " { $emphasis "address specifiers" } " rather than concrete concepts such as host names. There are four types of address specifiers."
+$nl
+"Unix domain sockets:"
 { $subsection local }
+{ $subsection <local> }
+"Internet host name/port number pairs; the host name is resolved to an IPv4 or IPv6 address using the operating system's resolver:"
 { $subsection inet }
+{ $subsection <inet> }
+"IPv4 addresses, with no host name resolution:"
 { $subsection inet4 }
+{ $subsection <inet4> }
+"IPv6 addresses, with no host name resolution:"
 { $subsection inet6 }
+{ $subsection <inet6> }
 "While the " { $link inet } " addressing specifier is capable of performing name lookups when passed to " { $link <client> } ", sometimes it is necessary to look up a host name without making a connection:"
 { $subsection resolve-host } ;
 
@@ -73,34 +82,42 @@ HELP: inet
     "This address specifier is only supported by " { $link <client> } ", which calls " { $link resolve-host }  " to obtain a list of IP addresses associated with the host name, and attempts a connection to each one in turn until one succeeds. Other network words do not accept this address specifier, and " { $link resolve-host } " must be called directly; it is then up to the application to pick the correct address from the (possibly several) addresses associated to the host name."
 }
 { $examples
-    { $code "\"www.apple.com\" \"http\" <inet>" }
+    { $code "\"www.apple.com\" 80 <inet>" }
-    { $code "\"localhost\" 8080 <inet>" }
 } ;
 
+HELP: <inet>
+{ $values { "host" "a host name" } { "port" "a port number" } }
+{ $description "Creates a new " { $link inet } " address specifier." } ;
+
 HELP: inet4
 { $class-description "IPv4 address/port number specifier for TCP/IP and UDP/IP connections. The " { $snippet "host" } " and " { $snippet "port" } " slots hold the IPv4 address and port number, respectively. New instances are created by calling " { $link <inet4> } "." }
-{ $notes
+{ $notes "Most applications do not operate on IPv4 addresses directly, and instead should use the " { $link inet } " address specifier, or call " { $link resolve-host } "." }
-"Most applications do not operate on IPv4 addresses directly, and instead should use " { $link resolve-host } " to look up the address associated to a host name. Also, try to support IPv6 where possible."
-}
 { $examples
     { $code "\"127.0.0.1\" 8080 <inet4>" }
 } ;
 
+HELP: <inet4>
+{ $values { "host" "an IPv4 address" } { "port" "a port number" } }
+{ $description "Creates a new " { $link inet4 } " address specifier." } ;
+
 HELP: inet6
 { $class-description "IPv6 address/port number specifier for TCP/IP and UDP/IP connections. The " { $snippet "host" } " and " { $snippet "port" } " slots hold the IPv6 address and port number, respectively. New instances are created by calling " { $link <inet6> } "." }
-{ $notes
+{ $notes "Most applications do not operate on IPv6 addresses directly, and instead should use the " { $link inet } " address specifier, or call " { $link resolve-host } "." }
-"Most applications do not operate on IPv6 addresses directly, and instead should use " { $link resolve-host } " to look up the address associated to a host name." }
 { $examples
     { $code "\"::1\" 8080 <inet6>" }
 } ;
 
+HELP: <inet6>
+{ $values { "host" "an IPv6 address" } { "port" "a port number" } }
+{ $description "Creates a new " { $link inet6 } " address specifier." } ;
+
 HELP: <client>
 { $values { "remote" "an address specifier" } { "encoding" "an encding descriptor" } { "stream" "a bidirectional stream" } { "local" "an address specifier" } }
 { $description "Opens a network connection and outputs a bidirectional stream using the given encoding, together with the local address the socket was bound to." }
 { $errors "Throws an error if the connection cannot be established." }
 { $notes "The " { $link with-client } " word is easier to use in most situations." }
 { $examples
-    { $code "\"www.apple.com\" \"http\" <inet> utf8 <client>" }
+    { $code "\"www.apple.com\" 80 <inet> utf8 <client>" }
 } ;
 
 HELP: with-client

core/growable/growable-docs.factor

@@ -28,7 +28,12 @@ HELP: new-size
 
 HELP: ensure
 { $values { "n" "a positive integer" } { "seq" growable } }
-{ $description "If " { $snippet "n" } " is less than the length of the sequence, does nothing. Otherwise, if " { $snippet "n" } " also exceeds the capacity of the underlying storage, the underlying storage is grown, and the fill pointer is reset. Finally, if " { $snippet "n" } " is greater than or equal to the length but less than the capacity of the underlying storage, the fill pointer is moved and nothing else is done."
+{ $description "This word behaves as follows, depending on the relation between " { $snippet "n" } " and the length of the sequence:"
-$nl
+{ $list
-"This word is used in the implementation of the " { $link set-nth } " generic for sequences supporting the resizable sequence protocol (see " { $link "growable" } ")."
+  { "If " { $snippet "n" } " is less than the length of the sequence, does nothing." }
+  { "If " { $snippet "n" } " exceeds the capacity of the underlying storage, the underlying storage is grown." }
+  { "If " { $snippet "n" } " is greater than or equal to the length but less than the capacity of the underlying storage, the fill pointer is moved and nothing else is done." }
+}
+"In the case that new elements are added to the sequence (last two cases), the new elements are undefined." }
+{ $notes "This word is used in the implementation of the " { $link set-nth } " generic for sequences supporting the resizable sequence protocol (see " { $link "growable" } ")."
 } ;