From 7eb831d3493c8d7591e4c8a55f05986b24fe275d Mon Sep 17 00:00:00 2001 From: Slava Pestov Date: Fri, 16 Jan 2009 13:30:43 -0600 Subject: [PATCH] Fix various documentation errors --- basis/io/directories/directories-docs.factor | 2 +- basis/io/sockets/sockets-docs.factor | 35 +++++++++++++++----- core/growable/growable-docs.factor | 11 ++++-- 3 files changed, 35 insertions(+), 13 deletions(-) diff --git a/basis/io/directories/directories-docs.factor b/basis/io/directories/directories-docs.factor index a469f5b816..427472db0f 100644 --- a/basis/io/directories/directories-docs.factor +++ b/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" } } diff --git a/basis/io/sockets/sockets-docs.factor b/basis/io/sockets/sockets-docs.factor index cfc33a02f6..caa268d85c 100644 --- a/basis/io/sockets/sockets-docs.factor +++ b/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 } +"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 } +"IPv4 addresses, with no host name resolution:" { $subsection inet4 } +{ $subsection } +"IPv6 addresses, with no host name resolution:" { $subsection inet6 } +{ $subsection } "While the " { $link inet } " addressing specifier is capable of performing name lookups when passed to " { $link } ", 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 } ", 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\" " } - { $code "\"localhost\" 8080 " } + { $code "\"www.apple.com\" 80 " } } ; +HELP: +{ $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 } "." } -{ $notes -"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." -} +{ $notes "Most applications do not operate on IPv4 addresses directly, and instead should use the " { $link inet } " address specifier, or call " { $link resolve-host } "." } { $examples { $code "\"127.0.0.1\" 8080 " } } ; +HELP: +{ $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 } "." } -{ $notes -"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." } +{ $notes "Most applications do not operate on IPv6 addresses directly, and instead should use the " { $link inet } " address specifier, or call " { $link resolve-host } "." } { $examples { $code "\"::1\" 8080 " } } ; +HELP: +{ $values { "host" "an IPv6 address" } { "port" "a port number" } } +{ $description "Creates a new " { $link inet6 } " address specifier." } ; + HELP: { $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\" utf8 " } + { $code "\"www.apple.com\" 80 utf8 " } } ; HELP: with-client diff --git a/core/growable/growable-docs.factor b/core/growable/growable-docs.factor index e1ab50cdcd..b55672f805 100644 --- a/core/growable/growable-docs.factor +++ b/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." -$nl -"This word is used in the implementation of the " { $link set-nth } " generic for sequences supporting the resizable sequence protocol (see " { $link "growable" } ")." +{ $description "This word behaves as follows, depending on the relation between " { $snippet "n" } " and the length of the sequence:" +{ $list + { "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" } ")." } ;