考慮有這樣的一個函數，這個函數會異步地連接到一個IPv4地址的TCP端口。我們通過例子來看文檔怎么寫：
~~~
/*
* Make a TCP connection to the given IPv4 address. Arguments:
*
* ip4addr a string representing a valid IPv4 address
*
* tcpPort a positive integer representing a valid TCP port
*
* timeout a positive integer denoting the number of milliseconds
* to wait for a response from the remote server before
* considering the connection to have failed.
*
* callback invoked when the connection succeeds or fails. Upon
* success, callback is invoked as callback(null, socket),
* where `socket` is a Node net.Socket object. Upon failure,
* callback is invoked as callback(err) instead.
*
* This function may fail for several reasons:
*
* SystemError For "connection refused" and "host unreachable" and other
* errors returned by the connect(2) system call. For these
* errors, err.errno will be set to the actual errno symbolic
* name.
*
* TimeoutError Emitted if "timeout" milliseconds elapse without
* successfully completing the connection.
*
* All errors will have the conventional "remoteIp" and "remotePort" properties.
* After any error, any socket that was created will be closed.
*/
function connect(ip4addr, tcpPort, timeout, callback)
{
assert.equal(typeof (ip4addr), 'string',
"argument 'ip4addr' must be a string");
assert.ok(net.isIPv4(ip4addr),
"argument 'ip4addr' must be a valid IPv4 address");
assert.equal(typeof (tcpPort), 'number',
"argument 'tcpPort' must be a number");
assert.ok(!isNaN(tcpPort) && tcpPort > 0 && tcpPort < 65536,
"argument 'tcpPort' must be a positive integer between 1 and 65535");
assert.equal(typeof (timeout), 'number',
"argument 'timeout' must be a number");
assert.ok(!isNaN(timeout) && timeout > 0,
"argument 'timeout' must be a positive integer");
assert.equal(typeof (callback), 'function');
/* do work */
}
~~~
這個例子在概念上很簡單，但是展示了上面我們所談論的一些建議：
* 參數，類型以及其它一些約束被清晰的文檔化。
* 這個函數對于接受的參數是非常嚴格的，并且會在得到錯誤參數的時候拋出異常（程序員的失誤）。
* 可能出現的操作失敗集合被記錄了。通過不同的”name“值可以區分不同的異常，而”errno“被用來獲得系統錯誤的詳細信息。
* 異常被傳遞的方式也被記錄了（通過失敗時調用回調函數）。
* 返回的錯誤有”remoteIp“和”remotePort“字段，這樣用戶就可以定義自己的錯誤了（比如，一個HTTP客戶端的端口號是隱含的）。
* 雖然很明顯，但是連接失敗后的狀態也被清晰的記錄了：所有被打開的套接字此時已經被關閉。
這看起來像是給一個很容易理解的函數寫了超過大部分人會寫的的超長注釋，但大部分函數實際上沒有這么容易理解。所有建議都應該被有選擇的吸收，如果事情很簡單，你應該自己做出判斷，但是記住：用十分鐘把預計發生的記錄下來可能之后會為你或其他人節省數個小時。
