aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorChristian von Roques <[email protected]>2010-12-15 17:36:09 -0400
committerNiclas Axelsson <[email protected]>2011-03-02 19:38:21 +0100
commit748dbeb1524122229373c5964334a8d8f18a525d (patch)
tree1d83be083538721e4cdb36fbfe7ced689a763be3
parentf38a6085c5c65c9324b58e1e2fa8815093688f96 (diff)
downloadotp-748dbeb1524122229373c5964334a8d8f18a525d.tar.gz
otp-748dbeb1524122229373c5964334a8d8f18a525d.tar.bz2
otp-748dbeb1524122229373c5964334a8d8f18a525d.zip
inets/httpc: Polish documentation
* Assure store_cookies (and verify_cookies) is documented instead of the nonexistent store_cookie and verify_cookie. * Make sure the cookies option is not called cookie in comments. * Sprinkle <c>...</c> arround symbols and code snippets in text. * Grammar, wording, and punctuation fixes. * Formalize See gen_tcp:connect/3,4 using <seealso>.
-rw-r--r--lib/inets/doc/src/http_client.xml8
-rw-r--r--lib/inets/doc/src/httpc.xml88
-rw-r--r--lib/inets/src/http_client/httpc.erl2
-rw-r--r--lib/kernel/doc/src/gen_tcp.xml1
4 files changed, 50 insertions, 49 deletions
diff --git a/lib/inets/doc/src/http_client.xml b/lib/inets/doc/src/http_client.xml
index 672ea3fa98..4542211d71 100644
--- a/lib/inets/doc/src/http_client.xml
+++ b/lib/inets/doc/src/http_client.xml
@@ -42,10 +42,10 @@
dynamically in runtime. Each client profile will spawn a new
process to handle each request unless there is a possibility to use
a persistent connection with or without pipelining.
- The client will add a host header and an empty
- te header if there are no such headers present in the request.</p>
+ The client will add a <c>host</c> header and an empty
+ <c>te</c> header if there are no such headers present in the request.</p>
- <p>The clients supports ipv6 as long as the underlying mechanisms also do
+ <p>The client supports ipv6 as long as the underlying mechanisms also do
so.</p>
</section>
@@ -87,7 +87,7 @@
httpc:request("http://www.erlang.org").
</code>
<p>An ordinary asynchronous request. The result will be sent
- to the calling process on the form {http, {ReqestId, Result}}</p>
+ to the calling process in the form <c>{http, {ReqestId, Result}}</c></p>
<code type="erl">
5 > {ok, RequestId} =
httpc:request(get, {"http://www.erlang.org", []}, [], [{sync, false}]).
diff --git a/lib/inets/doc/src/httpc.xml b/lib/inets/doc/src/httpc.xml
index 69e1009bc2..5d1f027e24 100644
--- a/lib/inets/doc/src/httpc.xml
+++ b/lib/inets/doc/src/httpc.xml
@@ -117,7 +117,7 @@ ssl_options() = {verify, code()} |
application or started dynamically in runtime by calling the
inets application API <c>inets:start(httpc, ServiceConfig)</c>, or
<c>inets:start(httpc, ServiceConfig, How)</c>
- see <seealso marker="inets">inets(3)</seealso> Below follows a
+ see <seealso marker="inets">inets(3)</seealso>. Below follows a
description of the available configuration options.</p>
<taglist>
<tag>{profile, profile()}</tag>
@@ -129,8 +129,8 @@ ssl_options() = {verify, code()} |
as session cookies.</item>
</taglist>
- <p>The client can be stopped using inets:stop(httpc, Pid) or
- inets:stop(httpc, Profile).</p>
+ <p>The client can be stopped using <c>inets:stop(httpc, Pid)</c> or
+ <c>inets:stop(httpc, Profile)</c>.</p>
<marker id="request1"></marker>
</section>
@@ -148,7 +148,7 @@ ssl_options() = {verify, code()} |
<v>Reason = term() </v>
</type>
<desc>
- <p>Equivalent to httpc:request(get, {Url, []}, [], []).</p>
+ <p>Equivalent to <c>httpc:request(get, {Url, []}, [], [])</c>.</p>
<marker id="request2"></marker>
</desc>
@@ -201,7 +201,7 @@ ssl_options() = {verify, code()} |
<desc>
<p>Sends a HTTP-request. The function can be both synchronous
and asynchronous. In the later case the function will return
- {ok, RequestId} and later on the information will be delivered
+ <c>{ok, RequestId}</c> and later on the information will be delivered
to the <c>receiver</c> depending on that value. </p>
<p>Http option (<c>http_option()</c>) details: </p>
@@ -267,12 +267,12 @@ ssl_options() = {verify, code()} |
<c>HTTP/0.9</c> client. By default this is an <c>HTTP/1.1</c>
client. When using <c>HTTP/1.0</c> persistent connections will
not be used. </p>
- <p>Defaults to the trsing <c>"HTTP/1.1"</c>. </p>
+ <p>Defaults to the string <c>"HTTP/1.1"</c>. </p>
</item>
<tag><c><![CDATA[relaxed]]></c></tag>
<item>
- <p>If set to true workarounds for known server deviations from
+ <p>If set to <c>true</c> workarounds for known server deviations from
the HTTP-standard are enabled. </p>
<p>Defaults to <c>false</c>. </p>
</item>
@@ -297,20 +297,20 @@ ssl_options() = {verify, code()} |
<p>Streams the body of a 200 or 206 response to the calling
process or to a file. When streaming to the calling process
using the option <c>self</c> the following stream messages
- will be sent to that process: {http, {RequestId,
+ will be sent to that process: <c>{http, {RequestId,
stream_start, Headers}, {http, {RequestId, stream,
- BinBodyPart}, {http, {RequestId, stream_end, Headers}. When
- streaming to the calling processes using the option
+ BinBodyPart}, {http, {RequestId, stream_end, Headers}</c>. When
+ streaming to to the calling processes using the option
<c>{self, once}</c> the first message will have an additional
- element e.i. {http, {RequestId, stream_start, Headers, Pid},
+ element e.i. <c>{http, {RequestId, stream_start, Headers, Pid}</c>,
this is the process id that should be used as an argument to
- http:stream_next/1 to trigger the next message to be sent to
+ <c>http:stream_next/1</c> to trigger the next message to be sent to
the calling process. </p>
<p>Note that it is possible that chunked encoding will add
- headers so that there are more headers in the stream_end
- message than in the stream_start.
+ headers so that there are more headers in the <c>stream_end</c>
+ message than in the <c>stream_start</c>.
When streaming to a file and the request is asynchronous the
- message {http, {RequestId, saved_to_file}} will be sent. </p>
+ message <c>{http, {RequestId, saved_to_file}}</c> will be sent. </p>
<p>Defaults to <c>none</c>. </p>
</item>
@@ -358,13 +358,13 @@ ssl_options() = {verify, code()} |
request handler. </p>
<p>By default the socket options set by the
<seealso marker="#set_options">set_options/1,2</seealso>
- function are used when establishing the connection. </p>
+ function are used when establishing a connection. </p>
</item>
<tag><c><![CDATA[receiver]]></c></tag>
<item>
- <p>Defines how the client will deliver the result for an
- asynchronous request (<c>sync</c> has the value
+ <p>Defines how the client will deliver the result of an
+ asynchroneous request (<c>sync</c> has the value
<c>false</c>). </p>
<taglist>
@@ -395,7 +395,7 @@ apply(Module, Function, [ReplyInfo | Args])
</item>
</taglist>
- <p>In all cases above, <c>ReplyInfo</c> has the following
+ <p>In all of the above cases, <c>ReplyInfo</c> has the following
structure: </p>
<pre>
@@ -470,46 +470,46 @@ apply(Module, Function, [ReplyInfo | Args])
<v>IpDesc = string()</v>
<d>ex: "134.138" or "[FEDC:BA98" (all IP-addresses starting with 134.138 or FEDC:BA98), "66.35.250.150" or "[2010:836B:4179::836B:4179]" (a complete IP-address).</d>
<v>MaxSessions = integer() </v>
- <d>Default is <em>2</em>.
+ <d>Default is <c>2</c>.
Maximum number of persistent connections to a host.</d>
<v>MaxKeepAlive = integer() </v>
- <d>Default is <em>5</em>.
+ <d>Default is <c>5</c>.
Maximum number of outstanding requests on the same connection to
a host.</d>
<v>KeepAliveTimeout = integer() </v>
- <d>Default is <em>120000</em> (= 2 min).
+ <d>Default is <c>120000</c> (= 2 min).
If a persistent connection is idle longer than the
- keep_alive_timeout the client will close the connection.
- The server may also have such a timeout but you should
+ <c>keep_alive_timeout</c> the client will close the connection.
+ The server may also have such a time out but you should
not count on it!</d>
<v>MaxPipeline = integer() </v>
- <d>Default is <em>2</em>.
+ <d>Default is <c>2</c>.
Maximum number of outstanding requests on a pipelined connection to a host.</d>
<v>PipelineTimeout = integer() </v>
- <d>Default is <em>0</em>,
+ <d>Default is <c>0</c>,
which will result in pipelining not being used.
If a persistent connection is idle longer than the
- pipeline_timeout the client will close the connection. </d>
+ <c>pipeline_timeout</c> the client will close the connection. </d>
<v>CookieMode = enabled | disabled | verify </v>
- <d>Default is <em>disabled</em>.
+ <d>Default is <c>disabled</c>.
If Cookies are enabled all valid cookies will automatically be
saved in the client manager's cookie database.
- If the option verify is used the function http:verify_cookie/2
- has to be called for the cookie to be saved.</d>
+ If the option <c>verify</c> is used the function <c>store_cookies/2</c>
+ has to be called for the cookies to be saved.</d>
<v>IpFamily = inet | inet6 | inet6fb4 </v>
- <d>By default <em>inet</em>.
+ <d>By default <c>inet</c>.
When it is set to <c>inet6fb4</c> you can use both ipv4 and ipv6.
It first tries <c>inet6</c> and if that does not works falls back to <c>inet</c>.
The option is here to provide a workaround for buggy ipv6 stacks to ensure that
ipv4 will always work.</d>
<v>IpAddress = ip_address() </v>
<d>If the host has several network interfaces, this option specifies which one to use.
- See gen_tcp:connect/3,4 for more info. </d>
+ See <seealso marker="kernel:gen_tcp#connect">gen_tcp:connect/3,4</seealso> for more info. </d>
<v>Port = integer() </v>
<d>Specify which local port number to use.
- See gen_tcp:connect/3,4 for more info. </d>
+ See <seealso marker="kernel:gen_tcp#connect">gen_tcp:connect/3,4</seealso> for more info. </d>
<v>VerboseMode = false | verbose | debug | trace </v>
- <d>Default is <em>false</em>.
+ <d>Default is <c>false</c>.
This option is used to switch on (or off)
different levels of erlang trace on the client.
It is a debug feature.</d>
@@ -523,14 +523,14 @@ apply(Module, Function, [ReplyInfo | Args])
alive and use persistent connections
with or without pipeline depending on configuration
and current circumstances. The HTTP/1.1 specification does not
- provide a guideline for how many requests that would be
+ provide a guideline for how many requests would be
ideal to be sent on a persistent connection,
this very much depends on the
application. Note that a very long queue of requests may cause a
user perceived delay as earlier requests may take a long time
to complete. The HTTP/1.1 specification does suggest a
limit of 2 persistent connections per server, which is the
- default value of the max_sessions option. </p>
+ default value of the <c>max_sessions</c> option. </p>
</note>
<marker id="stream_next"></marker>
@@ -549,14 +549,14 @@ apply(Module, Function, [ReplyInfo | Args])
<p>Triggers the next message to be streamed, e.i.
same behavior as active once for sockets.</p>
- <marker id="verify_cookie"></marker>
- <marker id="store_cookie"></marker>
+ <marker id="verify_cookies"></marker>
+ <marker id="store_cookies"></marker>
</desc>
</func>
<func>
- <name>store_cookie(SetCookieHeaders, Url) -> </name>
- <name>store_cookie(SetCookieHeaders, Url, Profile) -> ok | {error, Reason}</name>
+ <name>store_cookies(SetCookieHeaders, Url) -> </name>
+ <name>store_cookies(SetCookieHeaders, Url, Profile) -> ok | {error, Reason}</name>
<fsummary>Saves the cookies defined in SetCookieHeaders in the client profile's cookie database.</fsummary>
<type>
<v>SetCookieHeaders = headers() - where field = "set-cookie"</v>
@@ -566,7 +566,7 @@ apply(Module, Function, [ReplyInfo | Args])
<desc>
<p>Saves the cookies defined in SetCookieHeaders
in the client profile's cookie database. You need to
- call this function if you set the option cookies to <c>verify</c>.
+ call this function if you have set the option <c>cookies</c> to <c>verify</c>.
If no profile is specified the default profile will be used.
</p>
@@ -578,14 +578,14 @@ apply(Module, Function, [ReplyInfo | Args])
<name>cookie_header(Url) -> </name>
<name>cookie_header(Url, Profile) -> header() | {error, Rason}</name>
<fsummary>Returns the cookie header that would be sent when
- making a request to Url using the profile Profile.</fsummary>
+ making a request to Url using the profile <c>Profile</c>.</fsummary>
<type>
<v>Url = url()</v>
<v>Profile = profile()</v>
</type>
<desc>
<p>Returns the cookie header that would be sent
- when making a request to Url using the profile Profile.
+ when making a request to <c>Url</c> using the profile <c>Profile</c>.
If no profile is specified the default profile will be used.
</p>
@@ -602,7 +602,7 @@ apply(Module, Function, [ReplyInfo | Args])
<v>Profile = profile()</v>
</type>
<desc>
- <p>Resets (clears) the cookie database for the specified Profile.
+ <p>Resets (clears) the cookie database for the specified <c>Profile</c>.
If no profile is specified the default profile will be used.
</p>
</desc>
diff --git a/lib/inets/src/http_client/httpc.erl b/lib/inets/src/http_client/httpc.erl
index ae754fab94..04fae13b20 100644
--- a/lib/inets/src/http_client/httpc.erl
+++ b/lib/inets/src/http_client/httpc.erl
@@ -252,7 +252,7 @@ set_option(Key, Value, Profile) ->
%% Description: Store the cookies from <SetCookieHeaders>
%% in the cookie database
%% for the profile <Profile>. This function shall be used when the option
-%% cookie is set to verify.
+%% cookies is set to verify.
%%-------------------------------------------------------------------------
store_cookies(SetCookieHeaders, Url) ->
store_cookies(SetCookieHeaders, Url, default_profile()).
diff --git a/lib/kernel/doc/src/gen_tcp.xml b/lib/kernel/doc/src/gen_tcp.xml
index 8e7192a496..aa171c77c2 100644
--- a/lib/kernel/doc/src/gen_tcp.xml
+++ b/lib/kernel/doc/src/gen_tcp.xml
@@ -74,6 +74,7 @@ posix()
socket()
as returned by accept/1,2 and connect/3,4</code>
+ <marker id="connect"></marker>
</section>
<funcs>
<func>