File 5571-ftp-generate-documentation-from-source-cod... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 5571-ftp-generate-documentation-from-source-code.patch of Package erlang (Revision 33fb1bfcfb3bce757d0f7cfc6a9a3eaf)

Currently displaying revision 33fb1bfcfb3bce757d0f7cfc6a9a3eaf , Show latest

From ce8323bb96c3a3d267cd9acbb6dd6e8dfa99c3b0 Mon Sep 17 00:00:00 2001
From: Kiko Fernandez-Reyes <kiko@erlang.org>
Date: Fri, 17 Feb 2023 15:09:41 +0100
Subject: [PATCH 1/2] ftp: generate documentation from source code

Generates the types in the documentation of `ftp` from the source code.
Before this change, the documentation was hard-coded in `ftp.xml`.
---
 lib/ftp/doc/specs/.gitignore |   1 +
 lib/ftp/doc/src/Makefile     |   4 +
 lib/ftp/doc/src/ftp.xml      | 736 +++++++++++++----------------------
 lib/ftp/doc/src/specs.xml    |   4 +
 lib/ftp/test/ftp_SUITE.erl   |   2 +-
 5 files changed, 290 insertions(+), 457 deletions(-)
 create mode 100644 lib/ftp/doc/specs/.gitignore
 create mode 100644 lib/ftp/doc/src/specs.xml

diff --git a/lib/ftp/doc/specs/.gitignore b/lib/ftp/doc/specs/.gitignore
new file mode 100644
index 0000000000..322eebcb06
--- /dev/null
+++ b/lib/ftp/doc/specs/.gitignore
@@ -0,0 +1 @@
+specs_*.xml
diff --git a/lib/ftp/doc/src/Makefile b/lib/ftp/doc/src/Makefile
index 38ad4f76d0..6223dcc72b 100644
--- a/lib/ftp/doc/src/Makefile
+++ b/lib/ftp/doc/src/Makefile
@@ -54,6 +54,10 @@ XML_FILES = \
 	$(XML_REF3_FILES) \
 	$(XML_APPLICATION_FILES)
 
+SPEC_FILES = $(XML_REF3_FILES:%.xml=$(SPECDIR)/specs_%.xml)
+TOP_SPECS_FILE = specs.xml
+
+
 # IMAGE_FILES = ftp.gif
 
 include $(ERL_TOP)/make/doc.mk
diff --git a/lib/ftp/doc/src/ftp.xml b/lib/ftp/doc/src/ftp.xml
index a70369a777..7ea8023b24 100644
--- a/lib/ftp/doc/src/ftp.xml
+++ b/lib/ftp/doc/src/ftp.xml
@@ -81,203 +81,23 @@
 The FTP client can be started and stopped dynamically in runtime by
 calling the <c>ftp</c> application API
 <c>ftp:open(Host, Options)</c> and
- <c>ftp:close(Client)</c>.
-
- The available configuration options are as follows:
- 
- <taglist>
- <tag>{host, Host}</tag>
- <item>
- <marker id="host"></marker>
-	Host = <c>string() | ip_address()</c>
- </item>
-
- <tag>{port, Port}</tag>
- <item>
- <marker id="port"></marker>
-	Port = <c>integer() > 0</c>
-	Default is <c>0</c> which aliases to <c>21</c> or <c>990</c> when used with
-	 <seeerl marker="#open"><c>{tls_sec_method,ftps}</c></seeerl>).
- </item>
-
- <tag>{mode, Mode}</tag>
- <item>
- <marker id="mode"></marker>
-	Mode = <c>active | passive</c>
-	Default is <c>passive</c>. 
- </item>
-
- <tag>{verbose, Verbose}</tag>
- <item>
- <marker id="verbose"></marker>
-	Verbose = <c>boolean()</c> 
-	Determines if the FTP communication is to be
-	 verbose or not.
-	Default is <c>false</c>.
- </item>
-
- <tag>{debug, Debug}</tag>
- <item>
- <marker id="debug"></marker>
-	Debug = <c>trace | debug | disable</c> 
-	Debugging using the dbg toolkit. 
-	Default is <c>disable</c>.
- </item>
-
- <tag>{ipfamily, IpFamily}</tag>
- <item>
- <marker id="ipfamily"></marker>
-	IpFamily = <c>inet | inet6 | inet6fb4</c> 
-	With <c>inet6fb4</c> the client behaves as before, that is, 
-	 tries to use IPv6, and only if that does not work it
- uses IPv4).
-	Default is <c>inet</c> (IPv4).
- </item>
-
- <tag>{timeout, Timeout}</tag>
- <item>
- <marker id="timeout"></marker>
-	Timeout = <c>non_neg_integer()</c>
-	Connection time-out.
-	Default is <c>60000</c> (milliseconds).
- </item>
-
- <tag>{dtimeout, DTimeout}</tag>
- <item>
- <marker id="dtimeout"></marker>
-	DTimeout = <c>non_neg_integer() | infinity</c> 
-	Data connect time-out. 
-	The time the client waits for the server to connect to the 
-	data socket.
-	Default is <c>infinity</c>. 
- </item>
-
- <tag>{progress, Progress}</tag>
- <item>
- <marker id="progress"></marker>
-	Progress = <c>ignore | {CBModule, CBFunction, InitProgress}</c>
-	<c>CBModule = atom()</c>, <c>CBFunction = atom()</c>
-	<c>InitProgress = term()</c>
-	Default is <c>ignore</c>.
- </item> 
-
- </taglist>
- 
- Option <c>progress</c> is intended to be used by applications that
- want to create some type of progress report, such as a progress bar in
- a GUI. Default for the progress option is <c>ignore</c>,
- that is, the option is not used. When the progress option is
- specified, the following happens when <c>ftp:send/[3,4]</c> or
- <c>ftp:recv/[3,4]</c> are called:
- 
- <list type="bulleted">
- <item>
-	Before a file is transferred, the following call is
-	 made to indicate the start of the file transfer and how large
-	 the file is. The return value of the callback function
-	 is to be a new value for the <c>UserProgressTerm</c> that will
-	 be used as input the next time the callback function is
-	 called.
-	<c>
-	 CBModule:CBFunction(InitProgress, File, {file_size, FileSize})
-	</c>
- </item>
- 
- <item>
-	Every time a chunk of bytes is transferred the
-	 following call is made:
-	<c>
-	 CBModule:CBFunction(UserProgressTerm, File, {transfer_size, TransferSize})
- </c>
- </item>
-
- <item>
-	At the end of the file the following call is
-	 made to indicate the end of the transfer:
-	<c>
-	 CBModule:CBFunction(UserProgressTerm, File, {transfer_size, 0}) 
-	</c>
- </item>
- </list>
- 
- The callback function is to be defined as follows:
-
- <c>
-	CBModule:CBFunction(UserProgressTerm, File, Size) -> UserProgressTerm
- </c>
- 
- <c>
-	CBModule = CBFunction = atom()
- </c>
-
- <c>
-	UserProgressTerm = term()
- </c>
-
- <c>
-	File = string()
- </c>
-
- <c>
-	Size = {transfer_size, integer()} | {file_size, integer()} | {file_size, unknown}
- </c>
- 
- For remote files, <c>ftp</c> cannot determine the
- file size in a platform independent way. In this case the size
- becomes <c>unknown</c> and it is left to the application to
- determine the size.
- 
- <note>
- The callback is made by a middleman process, hence the
-	file transfer is not affected by the code in the progress
-	callback function. If the callback crashes, this is
-	detected by the FTP connection process, which then prints an
-	info-report and goes on as if the progress option was set
-	to <c>ignore</c>.
- </note>
- 
- The file transfer type is set to the default of the FTP server
- when the session is opened. This is usually ASCII mode.
- 
- 
- The current local working directory (compare <c>lpwd/1</c>) is set 
- to the value reported by <c>file:get_cwd/1</c>, the wanted
- local directory.
- 
- 
- The return value <c>Pid</c> is used as a reference to the
- newly created FTP client in all other functions, and they are to
- be called by the process that created the connection. The FTP
- client process monitors the process that created it and
- terminates if that process terminates. 
+ <c>ftp:close(Client)</c>. 
 </section>
 
 <section>
- <title>DATA TYPES</title>
+ <title>Data Types</title>
 The following type definitions are used by more than one
 function in the FTP client API:
 <c>pid()</c> = identifier of an FTP connection
 <c>string()</c> = list of ASCII characters
- <c>shortage_reason()</c> = <c>etnospc | epnospc</c>
- <c>restriction_reason()</c> = <c>epath | efnamena | elogin | enotbinary</c>
- - all restrictions are not always relevant to all functions
- 
- <c>common_reason()</c> = <c>econn | eclosed | term()</c> 
- - some explanation of what went wrong
-
 <marker id="account"></marker>
 </section>
 
 <funcs>
 
 <func>
- <name since="">account(Pid, Account) -> ok | {error, Reason}</name>
+ <name since="" name="account" arity="2" />
 <fsummary>Specifies which account to use.</fsummary>
- <type>
- <v>Pid = pid()</v>
- <v>Account = string()</v>
- <v>Reason = eacct | common_reason()</v>
- </type>
 <desc>
 Sets the account for an operation, if needed.
 
@@ -288,15 +108,10 @@
 </func>
 
 <func>
- <name since="">append(Pid, LocalFile) -> </name>
- <name since="">append(Pid, LocalFile, RemoteFile) -> ok | {error, Reason}</name>
- <fsummary>Transfers a file to remote server, and appends it to 
+ <name since="" name="append" arity="2"/>
+ <name since="" name="append" arity="3"/>
+ <fsummary>Transfers a file to remote server, and appends it to
 <c>Remotefile</c>.</fsummary>
- <type>
- <v>Pid = pid()</v>
- <v>LocalFile = RemoteFile = string()</v>
- <v>Reason = epath | elogin | etnospc | epnospc | efnamena | common_reason</v>
- </type>
 <desc>
 Transfers the file <c>LocalFile</c> to the remote server. If 
 <c>RemoteFile</c> is specified, the name of the remote file that the
@@ -309,17 +124,11 @@
 </func>
 
 <func>
- <name since="">append_bin(Pid, Bin, RemoteFile) -> ok | {error, Reason}</name>
+ <name since="" name="append_bin" arity="3"/>
 <fsummary>Transfers a binary into a remote file.</fsummary>
- <type>
- <v>Pid = pid()</v>
- <v>Bin = binary()</v>
- <v>RemoteFile = string()</v>
- <v>Reason = restriction_reason()| shortage_reason() | common_reason()</v>
- </type>
 <desc>
 Transfers the binary <c>Bin</c> to the remote server and appends 
- it to the file <c>RemoteFile</c>. If the file does not exist, it 
+ it to the file <c><anno>RemoteFile</anno></c>. If the file does not exist, it
 is created.
 
 <marker id="append_chunk"></marker>
@@ -327,15 +136,10 @@
 </func>
 
 <func>
- <name since="">append_chunk(Pid, Bin) -> ok | {error, Reason}</name>
+ <name since="" name="append_chunk" arity="2" />
 <fsummary>Appends a chunk to the remote file.</fsummary>
- <type>
- <v>Pid = pid()</v>
- <v>Bin = binary()</v>
- <v>Reason = echunk | restriction_reason() | common_reason()</v>
- </type>
 <desc>
- Transfers the chunk <c>Bin</c> to the remote server, which 
+ Transfers the chunk <c><anno>Bin</anno></c> to the remote server, which
 appends it to the file specified in the call to 
 <c>append_chunk_start/2</c>.
 For some errors, for example, file system full, it is 
@@ -347,16 +151,11 @@
 </func>
 
 <func>
- <name since="">append_chunk_start(Pid, File) -> ok | {error, Reason}</name>
+ <name since="" name="append_chunk_start" arity="2" />
 <fsummary>Starts transfer of file chunks for appending to <c>File</c>.</fsummary>
- <type>
- <v>Pid = pid()</v>
- <v>File = string()</v>
- <v>Reason = restriction_reason() | common_reason()</v>
- </type>
 <desc>
 Starts the transfer of chunks for appending to the file 
- <c>File</c> at the remote server. If the file does not exist, 
+ <c><anno>RemoteFile</anno></c> at the remote server. If the file does not exist,
 it is created.
 
 <marker id="append_chunk_end"></marker>
@@ -364,12 +163,8 @@
 </func>
 
 <func>
- <name since="">append_chunk_end(Pid) -> ok | {error, Reason}</name>
+ <name since="" name="append_chunk_end" arity="1"/>
 <fsummary>Stops transfer of chunks for appending.</fsummary>
- <type>
- <v>Pid = pid()</v>
- <v>Reason = echunk | restriction_reason() | shortage_reason() </v>
- </type>
 <desc>
 Stops transfer of chunks for appending to the remote server. 
 The file at the remote server, specified in the call to 
@@ -380,27 +175,19 @@
 </func>
 
 <func>
- <name since="">cd(Pid, Dir) -> ok | {error, Reason}</name>
+ <name since="" name="cd" arity="2" />
 <fsummary>Changes remote working directory.</fsummary>
- <type>
- <v>Pid = pid()</v>
- <v>Dir = string()</v>
- <v>Reason = restriction_reason() | common_reason() </v>
- </type>
 <desc>
 Changes the working directory at the remote server to 
- <c>Dir</c>.
+ <c><anno>Dir</anno></c>.
 
 <marker id="close"></marker>
 </desc>
 </func>
 
 <func>
- <name since="">close(Pid) -> ok</name>
+ <name since="" name="close" arity="1" />
 <fsummary>Ends the FTP session.</fsummary>
- <type>
-	<v>Pid = pid()</v>
- </type>
 <desc>
 	Ends an FTP session, created using function
 <seeerl marker="#open">open</seeerl>.
@@ -410,13 +197,8 @@
 </func>
 
 <func>
- <name since="">delete(Pid, File) -> ok | {error, Reason}</name>
+ <name since="" name="delete" arity="2"/>
 <fsummary>Deletes a file at the remote server.</fsummary>
- <type>
- <v>Pid = pid()</v>
- <v>File = string()</v>
- <v>Reason = restriction_reason() | common_reason()</v>
- </type>
 <desc>
 Deletes the file <c>File</c> at the remote server.
 
@@ -425,11 +207,8 @@
 </func>
 
 <func>
- <name since="">formaterror(Tag) -> string()</name>
+ <name since="" name="formaterror" arity="1"/>
 <fsummary>Returns error diagnostics.</fsummary>
- <type>
- <v>Tag = {error, atom()} | atom()</v>
- </type>
 <desc>
 Given an error return value <c>{error, AtomReason}</c>,
 this function returns a readable string describing the error.
@@ -439,26 +218,18 @@
 </func>
 
 <func>
- <name since="">lcd(Pid, Dir) -> ok | {error, Reason}</name>
+ <name since="" name="lcd" arity="2" />
 <fsummary>Changes local working directory.</fsummary>
- <type>
- <v>Pid = pid()</v>
- <v>Dir = string()</v>
- <v>Reason = restriction_reason()</v>
- </type>
 <desc>
- Changes the working directory to <c>Dir</c> for the local client.
+ Changes the working directory to <c><anno>Dir</anno></c> for the local client.
 
 <marker id="lpwd"></marker>
 </desc>
 </func>
 
 <func>
- <name since="">lpwd(Pid) -> {ok, Dir}</name>
+ <name since="" name="lpwd" arity="1" />
 <fsummary>Gets local current working directory.</fsummary>
- <type>
- <v>Pid = pid()</v>
- </type>
 <desc>
 Returns the current working directory at the local client.
 
@@ -469,21 +240,15 @@
 </func>
 
 <func>
- <name since="">ls(Pid) -> </name>
- <name since="">ls(Pid, Pathname) -> {ok, Listing} | {error, Reason}</name>
+ <name since="" name="ls" arity="1" />
+ <name since="" name="ls" arity="2" />
 <fsummary>List of files.</fsummary>
- <type>
- <v>Pid = pid()</v>
- <v>Pathname = string()</v>
- <v>Listing = string()</v>
- <v>Reason = restriction_reason() | common_reason()</v>
- </type>
 <desc>
 Returns a list of files in long format.
- <c>Pathname</c> can be a directory, a group of files, or 
- a file. The <c>Pathname</c> string can contain wildcards.
+ <c><anno>Dir</anno></c> can be a directory or
+ a file. The <c><anno>Dir</anno></c> string can contain wildcards.
 <c>ls/1</c> implies the current remote directory of the user.
- The format of <c>Listing</c> depends on the operating system. 
+ The format of <c><anno>Listing</anno></c> depends on the operating system.
 On UNIX, it is typically produced from the output of the 
 <c>ls -l</c> shell command.
 
@@ -492,15 +257,10 @@
 </func>
 
 <func>
- <name since="">mkdir(Pid, Dir) -> ok | {error, Reason}</name>
+ <name since="" name="mkdir" arity="2" />
 <fsummary>Creates a remote directory.</fsummary>
- <type>
- <v>Pid = pid()</v>
- <v>Dir = string()</v>
- <v>Reason = restriction_reason() | common_reason()</v>
- </type>
 <desc>
- Creates the directory <c>Dir</c> at the remote server.
+ Creates the directory <c><anno>Dir</anno></c> at the remote server.
 
 <marker id="nlist"></marker>
 <marker id="nlist1"></marker>
@@ -509,21 +269,15 @@
 </func>
 
 <func>
- <name since="">nlist(Pid) -> </name>
- <name since="">nlist(Pid, Pathname) -> {ok, Listing} | {error, Reason}</name>
+ <name since="" name="nlist" arity="1" />
+ <name since="" name="nlist" arity="2" />
 <fsummary>List of files.</fsummary>
- <type>
- <v>Pid = pid()</v>
- <v>Pathname = string()</v>
- <v>Listing = string()</v>
- <v>Reason = restriction_reason() | common_reason()</v>
- </type>
 <desc>
 Returns a list of files in short format.
- <c>Pathname</c> can be a directory, a group of files, or 
- a file. The <c>Pathname</c> string can contain wildcards.
+ <c><anno>Pathname</anno></c> can be a directory or
+ a file. The <c><anno>Pathname</anno></c> string can contain wildcards.
 <c>nlist/1</c> implies the current remote directory of the user.
- The format of <c>Listing</c> is a stream of
+ The format of <c><anno>Listing</anno></c> is a stream of
 filenames where each filename is separated by &lt;CRLF&gt; or
 &lt;NL&gt;. Contrary to function <c>ls</c>, the purpose of
 <c>nlist</c> is to enable a program to
@@ -534,76 +288,229 @@
 </func>
 
 <func>
- <name since="">open(Host) -> {ok, Pid} | {error, Reason}</name>
- <name since="">open(Host, Opts) -> {ok, Pid} | {error, Reason}</name>
+ <name since="" name="open" arity="1" />
+ <name since="" name="open" arity="2" />
 <fsummary>Starts a FTP client.</fsummary>
- <type>
-	<v>Host = string() | ip_address()</v>
-	<v>Opts = options()</v>
-	<v>options() = [option()]</v>
-	<v>option() = start_option() | open_option()</v>
-	<v>start_option() = {verbose, verbose()} | {debug, debug()}</v>
-	<v>verbose() = boolean() (default is false)</v>
-	<v>debug() = disable | debug | trace (default is disable)</v>
-	<v>open_option() = {ipfamily, ipfamily()} | {port, port()} | {mode, mode()} | {tls, tls_options()} | {tls_sec_method, tls_sec_method()} | {tls_ctrl_session_reuse, boolean() (default is false)} | {timeout, timeout()} | {dtimeout, dtimeout()} | {progress, progress()} | {sock_ctrl, sock_opts()} | {sock_data_act, sock_opts()} | {sock_data_pass, sock_opts()}</v>
-	<v>ipfamily() = inet | inet6 | inet6fb4 (default is inet)</v>
-	<v>port() = non_neg_integer() (default is 0 which aliases to 21 or 990 when used with {tls_sec_method,ftps})</v>
-	<v>mode() = active | passive (default is passive)</v>
-	<v>tls_options() = [<seetype marker="ssl:ssl#tls_option">ssl:tls_option()</seetype>]</v>
-	<v>tls_sec_method() = ftps | ftpes (default is ftpes)</v>
-	<v>sock_opts() = [<seetype marker="kernel:gen_tcp#option">gen_tcp:option()</seetype> except for ipv6_v6only, active, packet, mode, packet_size and header</v>
-	<v>timeout() = integer() > 0 (default is 60000 milliseconds)</v>
-	<v>dtimeout() = integer() > 0 | infinity (default is infinity)</v>
-	<v>progress() = ignore | {module(), function(), initial_data()} (default is ignore)</v>
-	<v>module() = atom()</v>
-	<v>function() = atom()</v>
-	<v>initial_data() = term()</v>
-	<v>Reason = ehost | term()</v>
- </type>
-
 <desc>
 	Starts a FTP client process and
 opens a session with the FTP server at <c>Host</c>. 
+ A session opened in this way is closed using function
+ <seeerl marker="#close">close</seeerl>.
+
+ The available configuration options are as follows:
 
-	If option <c>{tls, tls_options()}</c> is present, the FTP session 
-	is transported over <c>tls</c> (<c>ftps</c>, see 
-	<url href="http://www.ietf.org/rfc/rfc4217.txt">RFC 4217</url>). 
-	The list <c>tls_options()</c> can be empty. The function 
-	<seemfa marker="ssl:ssl#connect/3"><c>ssl:connect/3</c></seemfa> 
+ <taglist>
+ <tag>{host, Host}</tag>
+ <item>
+ <marker id="host"></marker>
+	Host = <c>string() | ip_address()</c>
+ </item>
+
+ <tag>{port, Port}</tag>
+ <item>
+ <marker id="port"></marker>
+	Default is <c>0</c> which aliases to <c>21</c> or <c>990</c> when used with
+	 <seeerl marker="#open"><c>{tls_sec_method,ftps}</c></seeerl>).
+ </item>
+
+ <tag>{mode, Mode}</tag>
+ <item>
+ <marker id="mode"></marker>
+	Default is <c>passive</c>.
+ </item>
+
+ <tag>{verbose, Verbose}</tag>
+ <item>
+ <marker id="verbose"></marker>
+	Determines if the FTP communication is to be
+	 verbose or not.
+	Default is <c>false</c>.
+ </item>
+
+ <tag>{debug, Debug}</tag>
+ <item>
+ <marker id="debug"></marker>
+	Debugging using the dbg toolkit. 
+	Default is <c>disable</c>.
+ </item>
+
+ <tag>{ipfamily, IpFamily}</tag>
+ <item>
+ <marker id="ipfamily"></marker>
+	With <c>inet6fb4</c> the client behaves as before, that is,
+	 tries to use IPv6, and only if that does not work it
+ uses IPv4).
+	Default is <c>inet</c> (IPv4).
+ </item>
+
+ <tag>{timeout, Timeout}</tag>
+ <item>
+ <marker id="timeout"></marker>
+	Connection time-out.
+	Default is <c>60000</c> (milliseconds).
+ </item>
+
+ <tag>{dtimeout, DTimeout}</tag>
+ <item>
+ <marker id="dtimeout"></marker>
+	Data connect time-out.
+	The time the client waits for the server to connect to the
+	data socket.
+	Default is <c>infinity</c>. 
+ </item>
+
+ <tag>{tls, TLSOptions}</tag>
+	<item><marker id="tls_options"></marker>
+ The FTP session is transported over <c>tls</c> (<c>ftps</c>, see
+	<url href="http://www.ietf.org/rfc/rfc4217.txt">RFC 4217</url>).
+	The list <c><anno>TLSOptions</anno></c> can be empty. The function
+	<seemfa marker="ssl:ssl#connect/3"><c>ssl:connect/3</c></seemfa>
 	is used for securing both the control connection and the data sessions.
 	
+ </item>
 
-	The suboption <c>{tls_sec_method, tls_sec_method()}</c> (defaults to
-	<c>ftpes</c>) when set to <c>ftps</c> will connect immediately with SSL
+ 	<tag>{tls_sec_method, TLSSecMethod}</tag>
+ <item><marker id="tls_sec_method"></marker>
+ When set to <c>ftps</c> will connect immediately with SSL
 	instead of upgrading with STARTTLS. This suboption is ignored unless
-	the suboption <c>tls</c> is also set.
-	
+	the suboption <c>tls</c> is also set.
+ Default is <c>ftpes</c>
+ </item>
 
-	The option <c>{tls_ctrl_session_reuse, boolean()}</c> (defaults to
-	<c>false</c>) when set to <c>true</c> the client will re-use the
+	<tag>{tls_ctrl_session_reuse, boolean()}</tag>
+ <item><marker id="tls_ctrl_session_reuse"></marker>
+ When set to <c>true</c> the client will re-use the
 	TLS session from the control channel on the data channel as enforced by
 	many FTP servers as (<url href="https://scarybeastsecurity.blogspot.com/2009/02/vsftpd-210-released.html">proposed and implemented first by vsftpd</url>).
 	
+ Default is <c>false</c>.
+ </item>
+
+ <tag>{sock_ctrl, SocketCtrls :: [SocketControl :: gen_tcp:option()]}</tag>
+ <item>
+ Passes options from <c>SocketCtrls</c> down to the underlying transport layer (tcp).
+ <seetype marker="kernel:gen_tcp#option">gen_tcp:option()</seetype> except for <c>ipv6_v6only</c>,
+ <c>active</c>, <c>packet</c>, <c>mode</c>, <c>packet_size</c> and <c>header</c>.
+ Default value is <c>SocketCtrls = []</c>.
+ </item>
+
+ <tag>{sock_data_act, [SocketControl]}</tag>
+ <item>
+ Passes options from <c>[SocketControl]</c> down to the underlying transport layer (tcp).
+ <c>sock_data_act</c> uses the value of <c>sock_ctrl</c> as default value.
+ </item>
+
+ <tag>{sock_data_pass, [SocketControl]}</tag>
+ <item>
+ Passes options from <c>[SocketControl]</c> down to the underlying transport layer (tcp).
+ 
+ <c>sock_data_pass</c> uses the value of <c>sock_ctrl</c> as default value.
+ </item>
 
-	The options <c>sock_ctrl</c>, <c>sock_data_act</c> and <c>sock_data_pass</c> passes options down to 
-	the underlying transport layer (tcp). The default value for <c>sock_ctrl</c> is <c>[]</c>. Both 
-	<c>sock_data_act</c> and <c>sock_data_pass</c> uses the value of <c>sock_ctrl</c> as default value.
-	
+ <tag>{progress, Progress}</tag>
+ <item>
+ <marker id="progress"></marker>
+	Progress = <c>ignore | {Module, Function, InitialData}</c>
+	<c>Module = atom()</c>, <c>Function = atom()</c>
+	<c>InitialData = term()</c>
+	Default is <c>ignore</c>.
+
+ Option <c>progress</c> is intended to be used by applications that
+ want to create some type of progress report, such as a progress bar in
+ a GUI. Default for the progress option is <c>ignore</c>,
+ that is, the option is not used. When the progress option is
+ specified, the following happens when <c>ftp:send/[3,4]</c> or
+ <c>ftp:recv/[3,4]</c> are called:
+
+ <list type="bulleted">
+ <item>
+	Before a file is transferred, the following call is
+	 made to indicate the start of the file transfer and how large
+	 the file is. The return value of the callback function
+	 is to be a new value for the <c>UserProgressTerm</c> that will
+	 be used as input the next time the callback function is
+	 called.
+	<c>
+	 Module:Function(InitialData, File, {file_size, FileSize})
+	</c>
+ </item>
+
+ <item>
+	Every time a chunk of bytes is transferred the
+	 following call is made:
+	<c>
+	 Module:Function(UserProgressTerm, File, {transfer_size, TransferSize})
+ </c>
+ </item>
+
+ <item>
+	At the end of the file the following call is
+	 made to indicate the end of the transfer:
+	<c>
+	 Module:Function(UserProgressTerm, File, {transfer_size, 0})
+	</c>
+ </item>
+ </list>
+
+ The callback function is to be defined as follows:
+
+ <c>
+	Module:Function(UserProgressTerm, File, Size) -> UserProgressTerm
+ </c>
+
+ <c>
+	UserProgressTerm = term()
+ </c>
+
+ <c>
+	File = string()
+ </c>
+
+ <c>
+	Size = {transfer_size, integer()} | {file_size, integer()} | {file_size, unknown}
+ </c>
+
+ For remote files, <c>ftp</c> cannot determine the
+ file size in a platform independent way. In this case the size
+ becomes <c>unknown</c> and it is left to the application to
+ determine the size.
+
+ <note>
+ The callback is made by a middleman process, hence the
+	file transfer is not affected by the code in the progress
+	callback function. If the callback crashes, this is
+	detected by the FTP connection process, which then prints an
+	info-report and goes on as if the progress option was set
+	to <c>ignore</c>.
+ </note>
+
+ The file transfer type is set to the default of the FTP server
+ when the session is opened. This is usually ASCII mode.
+ 
+
+ The current local working directory (compare <c>lpwd/1</c>) is set
+ to the value reported by <c>file:get_cwd/1</c>, the wanted
+ local directory.
+ 
+
+ The return value <c>Pid</c> is used as a reference to the
+ newly created FTP client in all other functions, and they are to
+ be called by the process that created the connection. The FTP
+ client process monitors the process that created it and
+ terminates if that process terminates.
+
+ </item>
+
+ </taglist>
 
- A session opened in this way is closed using function
- <seeerl marker="#close">close</seeerl>.
 
 <marker id="pwd"></marker>
 </desc>
 </func>
 
 <func>
- <name since="">pwd(Pid) -> {ok, Dir} | {error, Reason}</name>
+ <name since="" name="pwd" arity="1"/>
 <fsummary>Gets the remote current working directory.</fsummary>
- <type>
- <v>Pid = pid()</v>
- <v>Reason = restriction_reason() | common_reason()</v>
- </type>
 <desc>
 Returns the current working directory at the remote server.
 
@@ -614,23 +521,17 @@
 </func>
 
 <func>
- <name since="">recv(Pid, RemoteFile) -> </name>
- <name since="">recv(Pid, RemoteFile, LocalFile) -> ok | {error, Reason}</name>
+ <name since="" name="recv" arity="2"/>
+ <name since="" name="recv" arity="3"/>
 <fsummary>Transfers a file from remote server.</fsummary>
- <type>
- <v>Pid = pid()</v>
- <v>RemoteFile = LocalFile = string()</v>
- <v>Reason = restriction_reason() | common_reason() | file_write_error_reason() </v>
- <v>file_write_error_reason() = see file:write/2</v>
- </type>
- <desc>
- Transfers the file <c>RemoteFile</c> from the remote server
+ <desc>
+ Transfers the file <c><anno>RemoteFileName</anno></c> from the remote server
 to the file system of the local client. If
- <c>LocalFile</c> is specified, the local file will be
- <c>LocalFile</c>, otherwise
- <c>RemoteFile</c>.
- If the file write fails (for example, <c>enospc</c>), the command is 
-	aborted and <c>{error, file_write_error_reason()}</c> is returned. 
+ <c><anno>LocalFileName</anno></c> is specified, the local file will be
+ <c><anno>LocalFileName</anno></c>, otherwise
+ <c><anno>RemoteFileName</anno></c>.
+ If the file write fails, the command is
+	aborted and <c>{error, term()}</c> is returned.
 	However, the file is not removed.
 
 <marker id="recv_bin"></marker>
@@ -638,16 +539,10 @@
 </func>
 
 <func>
- <name since="">recv_bin(Pid, RemoteFile) -> {ok, Bin} | {error, Reason}</name>
+ <name since="" name="recv_bin" arity="2"/>
 <fsummary>Transfers a file from remote server as a binary.</fsummary>
- <type>
- <v>Pid = pid()</v>
- <v>Bin = binary()</v>
- <v>RemoteFile = string()</v>
- <v>Reason = restriction_reason() | common_reason()</v>
- </type>
- <desc>
- Transfers the file <c>RemoteFile</c> from the remote server and 
+ <desc>
+ Transfers the file <c><anno>RemoteFile</anno></c> from the remote server and
 receives it as a binary.
 
 <marker id="recv_chunk_start"></marker>
@@ -655,15 +550,10 @@
 </func>
 
 <func>
- <name since="">recv_chunk_start(Pid, RemoteFile) -> ok | {error, Reason}</name>
+ <name since="" name="recv_chunk_start" arity="2"/>
 <fsummary>Starts chunk-reading of the remote file.</fsummary>
- <type>
- <v>Pid = pid()</v>
- <v>RemoteFile = string()</v>
- <v>Reason = restriction_reason() | common_reason()</v>
- </type>
 <desc>
- Starts transfer of the file <c>RemoteFile</c> from the
+ Starts transfer of the file <c><anno>RemoteFile</anno></c> from the
 remote server.
 
 <marker id="recv_chunk"></marker>
@@ -671,15 +561,10 @@
 </func>
 
 <func>
- <name since="">recv_chunk(Pid) -> ok | {ok, Bin} | {error, Reason}</name>
+ <name since="" name="recv_chunk" arity="1" />
 <fsummary>Receives a chunk of the remote file.</fsummary>
- <type>
- <v>Pid = pid()</v>
- <v>Bin = binary()</v>
- <v>Reason = restriction_reason() | common_reason()</v>
- </type>
 <desc>
- Receives a chunk of the remote file (<c>RemoteFile</c> of 
+ Receives a chunk of the remote file (<c>RemoteFile</c> of
 <c>recv_chunk_start</c>). The return values have the following 
 meaning:
 <list type="bulleted">
@@ -693,30 +578,20 @@
 </func>
 
 <func>
- <name since="">rename(Pid, Old, New) -> ok | {error, Reason}</name>
+ <name since="" name="rename" arity="3"/>
 <fsummary>Renames a file at the remote server.</fsummary>
- <type>
- <v>Pid = pid()</v>
- <v>CurrFile = NewFile = string()</v>
- <v>Reason = restriction_reason() | common_reason()</v>
- </type>
 <desc>
- Renames <c>Old</c> to <c>New</c> at the remote server.
+ Renames <c><anno>Old</anno></c> to <c><anno>New</anno></c> at the remote server.
 
 <marker id="rmdir"></marker>
 </desc>
 </func>
 
 <func>
- <name since="">rmdir(Pid, Dir) -> ok | {error, Reason}</name>
+ <name since="" name="rmdir" arity="2" />
 <fsummary>Removes a remote directory.</fsummary>
- <type>
- <v>Pid = pid()</v>
- <v>Dir = string()</v>
- <v>Reason = restriction_reason() | common_reason()</v>
- </type>
 <desc>
- Removes directory <c>Dir</c> at the remote server.
+ Removes directory <c><anno>Dir</anno></c> at the remote server.
 
 <marker id="send"></marker>
 <marker id="send2"></marker>
@@ -725,34 +600,23 @@
 </func>
 
 <func>
- <name since="">send(Pid, LocalFile) -></name>
- <name since="">send(Pid, LocalFile, RemoteFile) -> ok | {error, Reason}</name>
+ <name since="" name="send" arity="2"/>
+ <name since="" name="send" arity="3"/>
 <fsummary>Transfers a file to the remote server.</fsummary>
- <type>
- <v>Pid = pid()</v>
- <v>LocalFile = RemoteFile = string()</v>
- <v>Reason = restriction_reason() | common_reason() | shortage_reason()</v>
- </type>
 <desc>
- Transfers the file <c>LocalFile</c> to the remote server. If 
- <c>RemoteFile</c> is specified, the name of the remote file is set
- to <c>RemoteFile</c>, otherwise to <c>LocalFile</c>.
+ Transfers the file <c><anno>LocalFileName</anno></c> to the remote server. If
+ <c><anno>RemoteFileName</anno></c> is specified, the name of the remote file is set
+ to <c><anno>RemoteFileName</anno></c>, otherwise to <c><anno>LocalFileName</anno></c>.
 
 <marker id="send_bin"></marker>
 </desc>
 </func>
 
 <func>
- <name since="">send_bin(Pid, Bin, RemoteFile) -> ok | {error, Reason}</name>
+ <name since="" name="send_bin" arity="3" />
 <fsummary>Transfers a binary into a remote file.</fsummary>
- <type>
- <v>Pid = pid()</v>
- <v>Bin = binary()</v>
- <v>RemoteFile = string()</v>
- <v>Reason = restriction_reason() | common_reason() | shortage_reason()</v>
- </type>
- <desc>
- Transfers the binary <c>Bin</c> into the file <c>RemoteFile</c> 
+ <desc>
+ Transfers the binary <c><anno>Bin</anno></c> into the file <c><anno>RemoteFile</anno></c>
 at the remote server.
 
 <marker id="send_chunk"></marker>
@@ -760,15 +624,10 @@
 </func>
 
 <func>
- <name since="">send_chunk(Pid, Bin) -> ok | {error, Reason}</name>
+ <name since="" name="send_chunk" arity="2" />
 <fsummary>Writes a chunk to the remote file.</fsummary>
- <type>
- <v>Pid = pid()</v>
- <v>Bin = binary()</v>
- <v>Reason = echunk | restriction_reason() | common_reason()</v>
- </type>
 <desc>
- Transfers the chunk <c>Bin</c> to the remote server, which 
+ Transfers the chunk <c><anno>Bin</anno></c> to the remote server, which
 writes it into the file specified in the call to 
 <c>send_chunk_start/2</c>.
 For some errors, for example, file system full, it is 
@@ -780,15 +639,10 @@
 </func>
 
 <func>
- <name since="">send_chunk_start(Pid, File) -> ok | {error, Reason}</name>
+ <name since="" name="send_chunk_start" arity="2" />
 <fsummary>Starts transfer of file chunks.</fsummary>
- <type>
- <v>Pid = pid()</v>
- <v>File = string()</v>
- <v>Reason = restriction_reason() | common_reason()</v>
- </type>
 <desc>
- Starts transfer of chunks into the file <c>File</c> at the 
+ Starts transfer of chunks into the file <c><anno>RemoteFile</anno></c> at the
 remote server.
 
 <marker id="send_chunk_end"></marker>
@@ -796,12 +650,8 @@
 </func>
 
 <func>
- <name since="">send_chunk_end(Pid) -> ok | {error, Reason}</name>
+ <name since="" name="send_chunk_end" arity="1" />
 <fsummary>Stops transfer of chunks.</fsummary>
- <type>
- <v>Pid = pid()</v>
- <v>Reason = restriction_reason() | common_reason() | shortage_reason()</v>
- </type>
 <desc>
 Stops transfer of chunks to the remote server. The file at the
 remote server, specified in the call to <c>send_chunk_start/2</c> 
@@ -812,14 +662,9 @@
 </func>
 
 <func>
- <name since="OTP 21.0">start_service(ServiceConfig) -> {ok, Pid} | {error, Reason}</name>
+ <name since="OTP 21.0" name="start_service" arity="1" />
 <fsummary>Dynamically starts an <c>FTP</c>
 session after the <c>ftp</c> application has been started.</fsummary>
- <type>
- <v>ServiceConfig = [{Option, Value}]</v>
-	<v>Option = property()</v>
-	<v>Value = term()</v>
- </type>
 <desc>
 Dynamically starts an <c>FTP</c> session after the <c>ftp</c>
 application has been started.
@@ -831,25 +676,19 @@
 </func>
 
 <func>
- <name since="OTP 21.0">stop_service(Reference) -> ok | {error, Reason} </name>
+ <name since="OTP 21.0" name="stop_service" arity="1"/>
 <fsummary>Stops an FTP session.</fsummary>
- <type>
-	<v>Reference = pid() | term() - service-specified reference</v>
-	<v>Reason = term()</v>
- </type>
+ <type_desc variable="Pid">
+ Service-specified reference
+ </type_desc>
 <desc>
 Stops a started FTP session.
 </desc>
 </func>
 
 <func>
- <name since="">type(Pid, Type) -> ok | {error, Reason}</name>
+ <name since="" name="type" arity="2" />
 <fsummary>Sets transfer type to <c>ascii</c>or <c>binary</c>.</fsummary>
- <type>
- <v>Pid = pid()</v>
- <v>Type = ascii | binary</v>
- <v>Reason = etype | restriction_reason() | common_reason()</v>
- </type>
 <desc>
 Sets the file transfer type to <c>ascii</c> or <c>binary</c>. When
 an FTP session is opened, the default transfer type of the
@@ -860,45 +699,30 @@
 </func>
 
 <func>
- <name since="">user(Pid, User, Password) -> ok | {error, Reason}</name>
+ <name since="" name="user" arity="3"/>
 <fsummary>User login.</fsummary>
- <type>
- <v>Pid = pid()</v>
- <v>User = Password = string()</v>
- <v>Reason = euser | common_reason()</v>
- </type>
 <desc>
- Performs login of <c>User</c> with <c>Password</c>.
+ Performs login of <c><anno>User</anno></c> with <c><anno>Pass</anno></c>.
 
 <marker id="user4"></marker>
 </desc>
 </func>
 
 <func>
- <name since="">user(Pid, User, Password, Account) -> ok | {error, Reason}</name>
+ <name since="" name="user" arity="4" />
 <fsummary>User login.</fsummary>
- <type>
- <v>Pid = pid()</v>
- <v>User = Password = string()</v>
- <v>Reason = euser | common_reason() </v>
- </type>
 <desc>
- Performs login of <c>User</c> with <c>Password</c> to the account 
- specified by <c>Account</c>.
+ Performs login of <c><anno>User</anno></c> with <c><anno>Pass</anno></c> to the account
+ specified by <c><anno>Account</anno></c>.
 
 <marker id="quote"></marker>
 </desc>
 </func>
 
 <func>
- <name since="">quote(Pid, Command) -> [FTPLine]</name>
+ <name since="" name="quote" arity="2" />
 <fsummary>Sends an arbitrary FTP command.</fsummary>
- <type>
- <v>Pid = pid()</v>
- <v>Command = string()</v>
- <v>FTPLine = string()</v>
- </type>
- <desc><note>The telnet end of line characters, from the FTP 
+ <desc><note>The telnet end of line characters, from the FTP
 protocol definition, CRLF, for example, "\\r\\n" has been removed.</note>
 Sends an arbitrary FTP command and returns verbatim a list
 of the lines sent back by the FTP server. This function is
diff --git a/lib/ftp/doc/src/specs.xml b/lib/ftp/doc/src/specs.xml
new file mode 100644
index 0000000000..a01aa83f78
--- /dev/null
+++ b/lib/ftp/doc/src/specs.xml
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<specs xmlns:xi="http://www.w3.org/2001/XInclude">
+ <xi:include href="../specs/specs_ftp.xml"/>
+</specs>
diff --git a/lib/ftp/test/ftp_SUITE.erl b/lib/ftp/test/ftp_SUITE.erl
index 961b3b5fe1..9239d18f74 100644
--- a/lib/ftp/test/ftp_SUITE.erl
+++ b/lib/ftp/test/ftp_SUITE.erl
@@ -1069,7 +1069,7 @@ error_ehost(_Config) ->
 %%%----------------------------------------------------------------
 error_datafail() ->
 [{doc, "Test that failure to open data channel captures "
- "error emitted on ctrl chanenel"}].
+ "error emitted on ctrl channel"}].
 
 error_datafail(Config) ->
 Self = self(),
-- 
2.35.3

Places

File 5571-ftp-generate-documentation-from-source-code.patch of Package erlang (Revision 33fb1bfcfb3bce757d0f7cfc6a9a3eaf)

Places