Skip to content

Commit b55b135

Browse files
JCMaisJCMais
committed
docs: major improvements to tsdoc
1 parent f032369 commit b55b135

22 files changed

+543
-166
lines changed

‎lib/Curl.ts

+193-78
Large diffs are not rendered by default.

‎lib/Easy.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ import { NodeLibcurlNativeBinding } from './types'
99
const bindings: NodeLibcurlNativeBinding = require('../lib/binding/node_libcurl.node')
1010

1111
/**
12-
* Easy Class
12+
* This is a Node.js wrapper around the binding {@link EasyNativeBinding | native Easy class}
1313
*
1414
* @public
1515
*/

‎lib/Multi.ts

+5-3
Original file line numberDiff line numberDiff line change
@@ -9,15 +9,17 @@ import { NodeLibcurlNativeBinding } from './types'
99
const bindings: NodeLibcurlNativeBinding = require('../lib/binding/node_libcurl.node')
1010

1111
/**
12-
* Multi class
12+
* This is a Node.js wrapper around the binding {@link MultiNativeBinding | native Multi class}.
13+
*
14+
* The only extra is that it provides a static field `option`.
1315
*
1416
* @public
1517
*/
1618
class Multi extends bindings.Multi {
1719
/**
18-
* Options to be used with `Multi.setOpt`
20+
* Options to be used with {@link setOpt | `setOpt`}.
1921
*
20-
* See the official documentation of [curl_multi_setopt()](http://curl.haxx.se/libcurl/c/curl_multi_setopt.html)
22+
* See the official documentation of [`curl_multi_setopt()`](http://curl.haxx.se/libcurl/c/curl_multi_setopt.html)
2123
* for reference.
2224
*
2325
* `CURLMOPT_MAXCONNECTS` becomes `Multi.option.MAXCONNECTS`

‎lib/Share.ts

+7-3
Original file line numberDiff line numberDiff line change
@@ -10,18 +10,22 @@ import { CurlShareOption } from './enum/CurlShareOption'
1010
const bindings: NodeLibcurlNativeBinding = require('../lib/binding/node_libcurl.node')
1111

1212
/**
13-
* Share class
13+
* This is a Node.js wrapper around the binding {@link EasyNativeBinding | native Easy class}.
14+
*
15+
* The only extra is that it provides a static field `option` and `lock`.
1416
*
1517
* @public
1618
*/
1719
class Share extends bindings.Share {
1820
/**
19-
* Options to be used with `Share.setOpt`
21+
* Options to be used with {@link setOpt | `setOpt`}.
2022
*
21-
* See the official documentation of [curl_share_setopt()](http://curl.haxx.se/libcurl/c/curl_share_setopt.html)
23+
* See the official documentation of [`curl_share_setopt()`](http://curl.haxx.se/libcurl/c/curl_share_setopt.html)
2224
* for reference.
2325
*
2426
* `CURLSHOPT_SHARE` becomes `Share.option.SHARE`
27+
*
28+
* @deprecated Use {@link CurlShareOption|`CurlShareOption`} directly instead.
2529
*/
2630
static option = CurlShareOption
2731
}

‎lib/enum/CurlFeature.ts

+1
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
*/
77

88
/**
9+
* Flags to be used with {@link "Curl".Curl.enable | `Curl#enable`} and {@link "Curl".Curl.disable | `Curl#disable`}
910
* @public
1011
*/
1112
export enum CurlFeature {

‎lib/enum/CurlFileType.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
*/
77
// https://github.com/curl/curl/blob/e1be8254534898/include/curl/curl.h#L264
88
/**
9-
* Object with constants on the `FileInfo` object,
9+
* Object with constants on the {@link FileInfo | `FileInfo`} object,
1010
* used alongside the `CHUNK_BGN_FUNCTION` option
1111
*
1212
* `CURLFILETYPE_DEVICE_BLOCK` becomes `CurlFileType.DeviceBlock`

‎lib/enum/CurlPause.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
*/
77
// https://github.com/curl/curl/blob/e1be8254/include/curl/curl.h#L2828
88
/**
9-
* Options to be used with `Easy.pause` or `Curl.pause`
9+
* Options to be used with {@link "Easy".Easy.pause | `Easy#pause`} and {@link "Curl".Curl.pause | `Curl#pause`}.
1010
*
1111
* `CURLPAUSE_RECV_CONT` becomes `CurlPause.RecvCont`
1212
*

‎lib/enum/CurlRtspRequest.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
// https://github.com/curl/curl/blob/e1be82545348/include/curl/curl.h#L1987
88
/**
99
* Object with constants for option `RTSP_REQUEST`
10-
* Only available on libcurl \>= 7.20
10+
* Only available on libcurl >= 7.20
1111
*
1212
* `CURL_RTSPREQ_OPTIONS` becomes `CurlRtspRequest.Options`
1313
*

‎lib/enum/CurlShareLock.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
*/
77
// https://github.com/curl/curl/blob/e1be82545348/include/curl/curl.h#L2643
88
/**
9-
* Options to be used with the `Curl.share.SHARE` and `Curl.share.UNSHARE` options.
9+
* Options to be used when setting `SHARE` or `UNSHARE` with {@link "Share".Share.setOpt | `Share#setOpt`}.
1010
*
1111
* `CURL_LOCK_DATA_SSL_SESSION` becomes `CurlShareLock.DataSslSession`
1212
*

‎lib/enum/CurlShareOption.ts

+2
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@
77
// https://github.com/curl/curl/blob/e1be82545348/include/curl/curl.h#L2685
88
// not following enum naming convention on this one to keep consistent with other curl options
99
/**
10+
* Options to be used with {@link "Share".Share.setOpt | `Share#setOpt`}.
11+
*
1012
* @public
1113
*/
1214
export enum CurlShareOption {

‎lib/enum/SocketState.ts

+2
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@
55
* LICENSE file in the root directory of this source tree.
66
*/
77
/**
8+
* This will be the type of the second parameter passed to the callback set with
9+
* {@link "Easy".Easy.onSocketEvent|`Easy#onSocketEvent`}.
810
* @public
911
*/
1012
export enum SocketState {

‎lib/index.ts

+5-6
Original file line numberDiff line numberDiff line change
@@ -4,18 +4,16 @@
44
* This source code is licensed under the MIT license found in the
55
* LICENSE file in the root directory of this source tree.
66
*/
7+
/**
8+
* node-libcurl
9+
* @packageDocumentation
10+
*/
711
export { Curl } from './Curl'
812
export { Easy } from './Easy'
913
export { Multi } from './Multi'
1014
export { Share } from './Share'
1115
export { curly, CurlyFunction, CurlyResult } from './curly'
1216

13-
// those are only for documentation purposes
14-
// export { Easy } from './Easy.doc'
15-
// export { Multi } from './Multi.doc'
16-
// export { Share } from './Share.doc'
17-
// export { curly, CurlyResult } from './curly.doc'
18-
1917
// enums
2018
export * from './enum/CurlAuth'
2119
export * from './enum/CurlChunk'
@@ -46,6 +44,7 @@ export * from './enum/CurlSslOpt'
4644
export * from './enum/CurlSslVersion'
4745
export * from './enum/CurlTimeCond'
4846
export * from './enum/CurlUseSsl'
47+
export * from './enum/CurlVersion'
4948
export * from './enum/CurlWriteFunc'
5049
export * from './enum/SocketState'
5150

‎lib/mergeChunks.ts

+2
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@
77
/**
88
* This function is used to merge the buffers
99
* that were stored while the request was being processed.
10+
*
11+
* @internal
1012
*/
1113
export function mergeChunks(chunks: Buffer[], length: number) {
1214
// We init the whole buffer below, so no need to use, the slower, Buffer.alloc

‎lib/parseHeaders.ts

+4
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@
55
* LICENSE file in the root directory of this source tree.
66
*/
77
/**
8+
* Whe data parsing is enabled on the {@link "Curl".Curl} instance, the headers parameter passed
9+
* to the `end` event's callback will be one array of this type.
810
* @public
911
*/
1012
export type HeaderInfo = {
@@ -20,6 +22,8 @@ export type HeaderInfo = {
2022
/**
2123
* Parses the headers that were stored while
2224
* the request was being processed.
25+
*
26+
* @internal
2327
*/
2428
export function parseHeaders(headersString: string): HeaderInfo[] {
2529
const headers = headersString.split(/\r?\n|\r/g)

‎lib/types/CurlNativeBinding.ts

+5
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,11 @@ import { CurlInfo } from '../generated/CurlInfo'
1010
import { CurlOption } from '../generated/CurlOption'
1111
import { MultiOption } from '../generated/MultiOption'
1212

13+
/**
14+
* This is the internal `Curl` object exported by the addon. It's not available for library users directly.
15+
*
16+
* @internal
17+
*/
1318
export declare interface CurlNativeBindingObject {
1419
globalInit(flags: CurlGlobalInit): number
1520
globalCleanup(): void

‎lib/types/CurlVersionInfoNativeBinding.ts

+91-2
Original file line numberDiff line numberDiff line change
@@ -4,20 +4,109 @@
44
* This source code is licensed under the MIT license found in the
55
* LICENSE file in the root directory of this source tree.
66
*/
7+
8+
import { CurlVersion } from '../enum/CurlVersion'
9+
10+
/**
11+
* This is the data returned on {@link Curl.getVersionInfo| `Curl.getVersionInfo`}.
12+
*
13+
* It's basically the output of [`curl_version_info()`](https://curl.haxx.se/libcurl/c/curl_version_info.html)
14+
*/
715
export declare interface CurlVersionInfoNativeBindingObject {
16+
/**
17+
* List of protocols supported. Example:
18+
* ```json
19+
* [
20+
* 'dict', 'file', 'ftp',
21+
* 'ftps', 'gopher', 'http',
22+
* 'https', 'imap', 'imaps',
23+
* 'ldap', 'ldaps', 'pop3',
24+
* 'pop3s', 'rtsp', 'scp',
25+
* 'sftp', 'smb', 'smbs',
26+
* 'smtp', 'smtps', 'telnet',
27+
* 'tftp'
28+
* ]
29+
* ```
30+
*/
831
protocols: string[]
32+
/**
33+
* List of features supported. Example:
34+
* ```json
35+
* [
36+
* 'AsynchDNS', 'IDN',
37+
* 'IPv6', 'Largefile',
38+
* 'SSPI', 'Kerberos',
39+
* 'SPNEGO', 'NTLM',
40+
* 'SSL', 'libz',
41+
* 'HTTP2', 'HTTPS-proxy'
42+
* ]
43+
* ```
44+
*/
945
features: string[]
10-
rawFeatures: number
46+
/**
47+
* Raw feature flags
48+
*/
49+
rawFeatures: CurlVersion
50+
/**
51+
* Libcurl version. Example:
52+
* ```
53+
* 7.69.1-DEV
54+
* ```
55+
*/
1156
version: string
57+
/**
58+
* Integer representation of libcurl version, created like this:
59+
* ```
60+
* <8 bits major number> | <8 bits minor number> | <8 bits patch number>.
61+
* ```
62+
* Version `7.69.1` is therefore returned as `0x074501`.
63+
*/
1264
versionNumber: number
65+
/**
66+
* SSL library human readable version string
67+
*/
1368
sslVersion: string
14-
sslVersionNum: number
69+
/**
70+
* This is not used - Will always be 0
71+
*/
72+
sslVersionNum: 0
73+
/**
74+
* libz human readable version string
75+
*/
1576
libzVersion: string
77+
/**
78+
* cares human readable version string
79+
* Will be null if libcurl was not built with cares
80+
*/
1681
aresVersion: string | null
82+
/**
83+
* cares version number
84+
* Will be null if libcurl was not built with cares
85+
*/
1786
aresVersionNumber: number
87+
/**
88+
* libidn human readable version string
89+
* Will be null if libcurl was not built with libidn
90+
*/
1891
libidnVersion: string | null
92+
/**
93+
* iconv version number
94+
* Will be 0 if libcurl was not built with iconv
95+
*/
1996
iconvVersionNumber: number
97+
/**
98+
* libssh human readable version string
99+
* Will be null if libcurl was not built with libssh
100+
*/
20101
libsshVersion: string | null
102+
/**
103+
* brotli version number
104+
* Will be 0 if libcurl was not built with brotli
105+
*/
21106
brotliVersionNumber: number
107+
/**
108+
* brotli human readable version string
109+
* Will be null if libcurl was not built with brotli
110+
*/
22111
brotliVersion: string | null
23112
}

0 commit comments

Comments
 (0)