From 8b980d729c712d2254618402f1e419ee14b85c5c Mon Sep 17 00:00:00 2001 From: Oleg Efimov Date: Thu, 18 Nov 2010 15:00:24 +0300 Subject: [PATCH] Fix line wrapping in docs. Add tics for constants in docs text. --- doc/api/addons.markdown | 2 +- doc/api/assert.markdown | 3 +- doc/api/crypto.markdown | 67 +++++++++++++++++++++++++++++--------------- doc/api/http.markdown | 27 ++++++++++++------ doc/api/net.markdown | 9 +++--- doc/api/path.markdown | 3 +- doc/api/process.markdown | 14 ++++++--- doc/api/querystring.markdown | 15 ++++++---- doc/api/repl.markdown | 4 +-- 9 files changed, 95 insertions(+), 49 deletions(-) diff --git a/doc/api/addons.markdown b/doc/api/addons.markdown index 1b29a03..29e4402 100644 --- a/doc/api/addons.markdown +++ b/doc/api/addons.markdown @@ -69,7 +69,7 @@ like this: Running `node-waf configure build` will create a file `build/default/hello.node` which is our Addon. -`node-waf` is just http://code.google.com/p/waf/[WAF], the python-based build system. `node-waf` is +`node-waf` is just [WAF](http://code.google.com/p/waf/), the python-based build system. `node-waf` is provided for the ease of users. All Node addons must export a function called `init` with this signature: diff --git a/doc/api/assert.markdown b/doc/api/assert.markdown index 6f5e91a..389fce2 100644 --- a/doc/api/assert.markdown +++ b/doc/api/assert.markdown @@ -45,4 +45,5 @@ Expects `block` not to throw an error. ### assert.ifError(value) -Tests if value is not a false value, throws if it is a true value. Useful when testing the first argument, `error` in callbacks. +Tests if value is not a false value, throws if it is a true value. Useful when +testing the first argument, `error` in callbacks. diff --git a/doc/api/crypto.markdown b/doc/api/crypto.markdown index c38b37f..9e83235 100644 --- a/doc/api/crypto.markdown +++ b/doc/api/crypto.markdown @@ -2,7 +2,9 @@ Use `require('crypto')` to access this module. -The crypto module requires OpenSSL to be available on the underlying platform. It offers a way of encapsulating secure credentials to be used as part of a secure HTTPS net or http connection. +The crypto module requires OpenSSL to be available on the underlying platform. +It offers a way of encapsulating secure credentials to be used as part +of a secure HTTPS net or http connection. It also offers a set of wrappers for OpenSSL's hash, hmac, cipher, decipher, sign and verify methods. @@ -14,23 +16,28 @@ Creates a credentials object, with the optional details being a dictionary with * `cert` : a string holding the PEM encoded certificate * `ca` : either a string or list of strings of PEM encoded CA certificates to trust. -If no 'ca' details are given, then node.js will use the default publicly trusted list of CAs as given in -http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt +If no 'ca' details are given, then node.js will use the default publicly trusted list of CAs as given in +. ### crypto.createHash(algorithm) -Creates and returns a hash object, a cryptographic hash with the given algorithm which can be used to generate hash digests. +Creates and returns a hash object, a cryptographic hash with the given algorithm +which can be used to generate hash digests. -`algorithm` is dependent on the available algorithms supported by the version of OpenSSL on the platform. Examples are sha1, md5, sha256, sha512, etc. On recent releases, `openssl list-message-digest-algorithms` will display the available digest algorithms. +`algorithm` is dependent on the available algorithms supported by the version +of OpenSSL on the platform. Examples are `'sha1'`, `'md5'`, `'sha256'`, `'sha512'`, etc. +On recent releases, `openssl list-message-digest-algorithms` will display the available digest algorithms. ### hash.update(data) -Updates the hash content with the given `data`. This can be called many times with new data as it is streamed. +Updates the hash content with the given `data`. +This can be called many times with new data as it is streamed. ### hash.digest(encoding='binary') -Calculates the digest of all of the passed data to be hashed. The `encoding` can be 'hex', 'binary' or 'base64'. +Calculates the digest of all of the passed data to be hashed. +The `encoding` can be `'hex'`, `'binary'` or `'base64'`. ### crypto.createHmac(algorithm, key) @@ -42,66 +49,82 @@ Creates and returns a hmac object, a cryptographic hmac with the given algorithm ### hmac.update(data) -Update the hmac content with the given `data`. This can be called many times with new data as it is streamed. +Update the hmac content with the given `data`. +This can be called many times with new data as it is streamed. ### hmac.digest(encoding='binary') -Calculates the digest of all of the passed data to the hmac. The `encoding` can be 'hex', 'binary' or 'base64'. +Calculates the digest of all of the passed data to the hmac. +The `encoding` can be `'hex'`, `'binary'` or `'base64'`. ### crypto.createCipher(algorithm, key) Creates and returns a cipher object, with the given algorithm and key. -`algorithm` is dependent on OpenSSL, examples are aes192, etc. On recent releases, `openssl list-cipher-algorithms` will display the available cipher algorithms. +`algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. +On recent releases, `openssl list-cipher-algorithms` will display the available cipher algorithms. ### cipher.update(data, input_encoding='binary', output_encoding='binary') -Updates the cipher with `data`, the encoding of which is given in `input_encoding` and can be 'utf8', 'ascii' or 'binary'. The `output_encoding` specifies the output format of the enciphered data, and can be 'binary', 'base64' or 'hex'. +Updates the cipher with `data`, the encoding of which is given in `input_encoding` +and can be `'utf8'`, `'ascii'` or `'binary'`. The `output_encoding` specifies +the output format of the enciphered data, and can be `'binary'`, `'base64'` or `'hex'`. Returns the enciphered contents, and can be called many times with new data as it is streamed. ### cipher.final(output_encoding='binary') -Returns any remaining enciphered contents, with `output_encoding` being one of: 'binary', 'ascii' or 'utf8'. +Returns any remaining enciphered contents, with `output_encoding` being one of: `'binary'`, `'ascii'` or `'utf8'`. ### crypto.createDecipher(algorithm, key) -Creates and returns a decipher object, with the given algorithm and key. This is the mirror of the cipher object above. +Creates and returns a decipher object, with the given algorithm and key. +This is the mirror of the cipher object above. ### decipher.update(data, input_encoding='binary', output_encoding='binary') -Updates the decipher with `data`, which is encoded in 'binary', 'base64' or 'hex'. The `output_decoding` specifies in what format to return the deciphered plaintext - either 'binary', 'ascii' or 'utf8'. +Updates the decipher with `data`, which is encoded in `'binary'`, `'base64'` or `'hex'`. +The `output_decoding` specifies in what format to return the deciphered plaintext: `'binary'`, `'ascii'` or `'utf8'`. ### decipher.final(output_encoding='binary') -Returns any remaining plaintext which is deciphered, with `output_encoding' being one of: 'binary', 'ascii' or 'utf8'. +Returns any remaining plaintext which is deciphered, +with `output_encoding' being one of: `'binary'`, `'ascii'` or `'utf8'`. ### crypto.createSign(algorithm) -Creates and returns a signing object, with the given algorithm. On recent OpenSSL releases, `openssl list-public-key-algorithms` will display the available signing algorithms. Examples are 'RSA-SHA256'. +Creates and returns a signing object, with the given algorithm. +On recent OpenSSL releases, `openssl list-public-key-algorithms` will display +the available signing algorithms. Examples are `'RSA-SHA256'`. ### signer.update(data) -Updates the signer object with data. This can be called many times with new data as it is streamed. +Updates the signer object with data. +This can be called many times with new data as it is streamed. ### signer.sign(private_key, output_format='binary') -Calculates the signature on all the updated data passed through the signer. `private_key` is a string containing the PEM encoded private key for signing. +Calculates the signature on all the updated data passed through the signer. +`private_key` is a string containing the PEM encoded private key for signing. -Returns the signature in `output_format` which can be 'binary', 'hex' or 'base64' +Returns the signature in `output_format` which can be `'binary'`, `'hex'` or `'base64'`. ### crypto.createVerify(algorithm) -Creates and returns a verification object, with the given algorithm. This is the mirror of the signing object above. +Creates and returns a verification object, with the given algorithm. +This is the mirror of the signing object above. ### verifier.update(data) -Updates the verifyer object with data. This can be called many times with new data as it is streamed. +Updates the verifyer object with data. +This can be called many times with new data as it is streamed. ### verifier.verify(public_key, signature, signature_format='binary') -Verifies the signed data by using the `public_key` which is a string containing the PEM encoded public key, and `signature`, which is the previously calculates signature for the data, in the `signature_format` which can be 'binary', 'hex' or 'base64'. +Verifies the signed data by using the `public_key` which is a string containing +the PEM encoded public key, and `signature`, which is the previously calculates +signature for the data, in the `signature_format` which can be `'binary'`, `'hex'` or `'base64'`. Returns true or false depending on the validity of the signature for the data and public key. diff --git a/doc/api/http.markdown b/doc/api/http.markdown index 99ffdf1..8eb958c 100644 --- a/doc/api/http.markdown +++ b/doc/api/http.markdown @@ -123,9 +123,14 @@ when the server has been bound. ### server.setSecure(credentials) -Enables HTTPS support for the server, with the crypto module credentials specifying the private key and certificate of the server, and optionally the CA certificates for use in client authentication. +Enables HTTPS support for the server, with the crypto module credentials +specifying the private key and certificate of the server, and optionally +the CA certificates for use in client authentication. -If the credentials hold one or more CA certificates, then the server will request for the client to submit a client certificate as part of the HTTPS connection handshake. The validity and content of this can be accessed via verifyPeer() and getPeerCertificate() from the server's request.connection. +If the credentials hold one or more CA certificates, then the server will request +for the client to submit a client certificate as part of the HTTPS connection handshake. +The validity and content of this can be accessed via `verifyPeer()` +and `getPeerCertificate()` from the server's `request.connection`. ### server.close() @@ -134,8 +139,8 @@ Stops the server from accepting new connections. ## http.ServerRequest -This object is created internally by a HTTP server--not by -the user--and passed as the first argument to a `'request'` listener. +This object is created internally by a HTTP server -- not by +the user -- and passed as the first argument to a `'request'` listener. This is an `EventEmitter` with the following events: @@ -382,9 +387,13 @@ Constructs a new HTTP client. `port` and `host` refer to the server to be connected to. A stream is not established until a request is issued. -`secure` is an optional boolean flag to enable https support and `credentials` is an optional credentials object from the crypto module, which may hold the client's private key, certificate, and a list of trusted CA certificates. +`secure` is an optional boolean flag to enable https support and `credentials` is an optional +credentials object from the crypto module, which may hold the client's private key, +certificate, and a list of trusted CA certificates. -If the connection is secure, but no explicit CA certificates are passed in the credentials, then node.js will default to the publicly trusted list of CA certificates, as given in http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt +If the connection is secure, but no explicit CA certificates are passed +in the credentials, then node.js will default to the publicly trusted list +of CA certificates, as given in . ### client.request(method='GET', path, [request_headers]) @@ -407,11 +416,13 @@ the user to stream a body to the server with `request.write()`.) ### client.verifyPeer() -Returns true or false depending on the validity of the server's certificate in the context of the defined or default list of trusted CA certificates. +Returns true or false depending on the validity of the server's certificate +in the context of the defined or default list of trusted CA certificates. ### client.getPeerCertificate() -Returns a JSON structure detailing the server's certificate, containing a dictionary with keys for the certificate 'subject', 'issuer', 'valid\_from' and 'valid\_to' +Returns a JSON structure detailing the server's certificate, containing a dictionary +with keys for the certificate `'subject'`, `'issuer'`, `'valid_from'` and `'valid_to'`. ## http.ClientRequest diff --git a/doc/api/net.markdown b/doc/api/net.markdown index 24d1e43..4e6bbef 100644 --- a/doc/api/net.markdown +++ b/doc/api/net.markdown @@ -168,7 +168,7 @@ for use in peer authentication. If the credentials hold one ore more CA certificates, then the stream will request for the peer to submit a client certificate as part of the SSL connection handshake. -The validity and content of this can be accessed via verifyPeer() and getPeerCertificate(). +The validity and content of this can be accessed via `verifyPeer()` and `getPeerCertificate()`. #### stream.verifyPeer() @@ -178,7 +178,7 @@ context of the defined or default list of trusted CA certificates. #### stream.getPeerCertificate() Returns a JSON structure detailing the peer's certificate, containing a dictionary -with keys for the certificate 'subject', 'issuer', 'valid\_from' and 'valid\_to' +with keys for the certificate `'subject'`, `'issuer'`, `'valid_from'` and `'valid_to'`. #### stream.write(data, encoding='ascii') @@ -315,9 +315,8 @@ following this event. `function (had_error) { }` -Emitted once the stream is fully closed. The argument `had_error` is a boolean which says if -the stream was closed due to a transmission -error. +Emitted once the stream is fully closed. The argument `had_error` is a boolean +which says if the stream was closed due to a transmission error. --- diff --git a/doc/api/path.markdown b/doc/api/path.markdown index bf6bf38..2e0c9e0 100644 --- a/doc/api/path.markdown +++ b/doc/api/path.markdown @@ -74,7 +74,8 @@ the first character, then it returns an empty string. Examples: ### path.exists(p, [callback]) -Test whether or not the given path exists. Then, call the `callback` argument with either true or false. Example: +Test whether or not the given path exists. Then, call the `callback` argument +with either true or false. Example: path.exists('/etc/passwd', function (exists) { util.debug(exists ? "it's there" : "no passwd!"); diff --git a/doc/api/process.markdown b/doc/api/process.markdown index 3dda98e..8094dcf 100644 --- a/doc/api/process.markdown +++ b/doc/api/process.markdown @@ -170,14 +170,17 @@ The shell that executed node should see the exit code as 1. ### process.getgid() -Gets the group identity of the process. (See getgid(2).) This is the numerical group id, not the group name. +Gets the group identity of the process. (See getgid(2).) +This is the numerical group id, not the group name. console.log('Current gid: ' + process.getgid()); ### process.setgid(id) -Sets the group identity of the process. (See setgid(2).) This accepts either a numerical ID or a groupname string. If a groupname is specified, this method blocks while resolving it to a numerical ID. +Sets the group identity of the process. (See setgid(2).) This accepts either +a numerical ID or a groupname string. If a groupname is specified, this method +blocks while resolving it to a numerical ID. console.log('Current gid: ' + process.getgid()); try { @@ -191,14 +194,17 @@ Sets the group identity of the process. (See setgid(2).) This accepts either a ### process.getuid() -Gets the user identity of the process. (See getuid(2).) This is the numerical userid, not the username. +Gets the user identity of the process. (See getuid(2).) +This is the numerical userid, not the username. console.log('Current uid: ' + process.getuid()); ### process.setuid(id) -Sets the user identity of the process. (See setuid(2).) This accepts either a numerical ID or a username string. If a username is specified, this method blocks while resolving it to a numerical ID. +Sets the user identity of the process. (See setuid(2).) This accepts either +a numerical ID or a username string. If a username is specified, this method +blocks while resolving it to a numerical ID. console.log('Current uid: ' + process.getuid()); try { diff --git a/doc/api/querystring.markdown b/doc/api/querystring.markdown index 66819cd..edb6d64 100644 --- a/doc/api/querystring.markdown +++ b/doc/api/querystring.markdown @@ -1,10 +1,12 @@ ## Query String -This module provides utilities for dealing with query strings. It provides the following methods: +This module provides utilities for dealing with query strings. +It provides the following methods: ### querystring.stringify(obj, sep='&', eq='=') -Serialize an object to a query string. Optionally override the default separator and assignment characters. +Serialize an object to a query string. +Optionally override the default separator and assignment characters. Example: @@ -18,7 +20,8 @@ Example: ### querystring.parse(str, sep='&', eq='=') -Deserialize a query string to an object. Optionally override the default separator and assignment characters. +Deserialize a query string to an object. +Optionally override the default separator and assignment characters. Example: @@ -28,8 +31,10 @@ Example: ### querystring.escape -The escape function used by `querystring.stringify`, provided so that it could be overridden if necessary. +The escape function used by `querystring.stringify`, +provided so that it could be overridden if necessary. ### querystring.unescape -The unescape function used by `querystring.parse`, provided so that it could be overridden if necessary. +The unescape function used by `querystring.parse`, +provided so that it could be overridden if necessary. diff --git a/doc/api/repl.markdown b/doc/api/repl.markdown index 761626b..0bc5c16 100644 --- a/doc/api/repl.markdown +++ b/doc/api/repl.markdown @@ -95,8 +95,8 @@ Things in the `context` object appear as local within the REPL: There are a few special REPL commands: - - `.break` - While inputting a multi-line expression, sometimes you get lost or just don't care - about completing it. `.break` will start over. + - `.break` - While inputting a multi-line expression, sometimes you get lost + or just don't care about completing it. `.break` will start over. - `.clear` - Resets the `context` object to an empty object and clears any multi-line expression. - `.exit` - Close the I/O stream, which will cause the REPL to exit. - `.help` - Show this list of special commands. -- 2.7.4