docs: major improvements to tsdoc

JCMais · JCMais · commit b55b13529c9d · 2020-05-28T18:47:23.000-03:00
diff --git a/lib/Curl.ts b/lib/Curl.ts
diff --git a/lib/Easy.ts b/lib/Easy.ts
@@ -9,7 +9,7 @@ import { NodeLibcurlNativeBinding } from './types'
 const bindings: NodeLibcurlNativeBinding = require('../lib/binding/node_libcurl.node')
 
 /**
- * Easy Class
+ * This is a Node.js wrapper around the binding {@link EasyNativeBinding | native Easy class}
  *
  * @public
  */
diff --git a/lib/Multi.ts b/lib/Multi.ts
@@ -9,15 +9,17 @@ import { NodeLibcurlNativeBinding } from './types'
 const bindings: NodeLibcurlNativeBinding = require('../lib/binding/node_libcurl.node')
 
 /**
- * Multi class
+ * This is a Node.js wrapper around the binding {@link MultiNativeBinding | native Multi class}.
+ *
+ * The only extra is that it provides a static field `option`.
  *
  * @public
  */
 class Multi extends bindings.Multi {
   /**
-   * Options to be used with `Multi.setOpt`
+   * Options to be used with {@link setOpt | `setOpt`}.
    *
-   * See the official documentation of [curl_multi_setopt()](http://curl.haxx.se/libcurl/c/curl_multi_setopt.html)
+   * See the official documentation of [`curl_multi_setopt()`](http://curl.haxx.se/libcurl/c/curl_multi_setopt.html)
    *  for reference.
    *
    * `CURLMOPT_MAXCONNECTS` becomes `Multi.option.MAXCONNECTS`
diff --git a/lib/Share.ts b/lib/Share.ts
@@ -10,18 +10,22 @@ import { CurlShareOption } from './enum/CurlShareOption'
 const bindings: NodeLibcurlNativeBinding = require('../lib/binding/node_libcurl.node')
 
 /**
- * Share class
+ * This is a Node.js wrapper around the binding {@link EasyNativeBinding | native Easy class}.
+ *
+ * The only extra is that it provides a static field `option` and `lock`.
  *
  * @public
  */
 class Share extends bindings.Share {
   /**
-   * Options to be used with `Share.setOpt`
+   * Options to be used with {@link setOpt | `setOpt`}.
    *
-   * See the official documentation of [curl_share_setopt()](http://curl.haxx.se/libcurl/c/curl_share_setopt.html)
+   * See the official documentation of [`curl_share_setopt()`](http://curl.haxx.se/libcurl/c/curl_share_setopt.html)
    *  for reference.
    *
    * `CURLSHOPT_SHARE` becomes `Share.option.SHARE`
+   *
+   * @deprecated Use {@link CurlShareOption|`CurlShareOption`} directly instead.
    */
   static option = CurlShareOption
 }
diff --git a/lib/enum/CurlFeature.ts b/lib/enum/CurlFeature.ts
@@ -6,6 +6,7 @@
  */
 
 /**
+ * Flags to be used with {@link "Curl".Curl.enable | `Curl#enable`} and {@link "Curl".Curl.disable | `Curl#disable`}
  * @public
  */
 export enum CurlFeature {
diff --git a/lib/enum/CurlFileType.ts b/lib/enum/CurlFileType.ts
@@ -6,7 +6,7 @@
  */
 // https://github.com/curl/curl/blob/e1be8254534898/include/curl/curl.h#L264
 /**
- * Object with constants on the `FileInfo` object,
+ * Object with constants on the {@link FileInfo | `FileInfo`} object,
  *  used alongside the `CHUNK_BGN_FUNCTION` option
  *
  * `CURLFILETYPE_DEVICE_BLOCK` becomes `CurlFileType.DeviceBlock`
diff --git a/lib/enum/CurlPause.ts b/lib/enum/CurlPause.ts
@@ -6,7 +6,7 @@
  */
 // https://github.com/curl/curl/blob/e1be8254/include/curl/curl.h#L2828
 /**
- * Options to be used with `Easy.pause` or `Curl.pause`
+ * Options to be used with {@link "Easy".Easy.pause | `Easy#pause`} and {@link "Curl".Curl.pause | `Curl#pause`}.
  *
  * `CURLPAUSE_RECV_CONT` becomes `CurlPause.RecvCont`
  *
diff --git a/lib/enum/CurlRtspRequest.ts b/lib/enum/CurlRtspRequest.ts
@@ -7,7 +7,7 @@
 // https://github.com/curl/curl/blob/e1be82545348/include/curl/curl.h#L1987
 /**
  * Object with constants for option `RTSP_REQUEST`
- * Only available on libcurl \>= 7.20
+ * Only available on libcurl >= 7.20
  *
  * `CURL_RTSPREQ_OPTIONS` becomes `CurlRtspRequest.Options`
  *
diff --git a/lib/enum/CurlShareLock.ts b/lib/enum/CurlShareLock.ts
@@ -6,7 +6,7 @@
  */
 // https://github.com/curl/curl/blob/e1be82545348/include/curl/curl.h#L2643
 /**
- * Options to be used with the `Curl.share.SHARE` and `Curl.share.UNSHARE` options.
+ * Options to be used when setting `SHARE` or `UNSHARE` with {@link "Share".Share.setOpt | `Share#setOpt`}.
  *
  * `CURL_LOCK_DATA_SSL_SESSION` becomes `CurlShareLock.DataSslSession`
  *
diff --git a/lib/enum/CurlShareOption.ts b/lib/enum/CurlShareOption.ts
@@ -7,6 +7,8 @@
 // https://github.com/curl/curl/blob/e1be82545348/include/curl/curl.h#L2685
 // not following enum naming convention on this one to keep consistent with other curl options
 /**
+ * Options to be used with {@link "Share".Share.setOpt | `Share#setOpt`}.
+ *
  * @public
  */
 export enum CurlShareOption {
diff --git a/lib/enum/SocketState.ts b/lib/enum/SocketState.ts
@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 /**
+ * This will be the type of the second parameter passed to the callback set with
+ *  {@link "Easy".Easy.onSocketEvent|`Easy#onSocketEvent`}.
  * @public
  */
 export enum SocketState {
diff --git a/lib/index.ts b/lib/index.ts
@@ -4,18 +4,16 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+/**
+ * node-libcurl
+ * @packageDocumentation
+ */
 export { Curl } from './Curl'
 export { Easy } from './Easy'
 export { Multi } from './Multi'
 export { Share } from './Share'
 export { curly, CurlyFunction, CurlyResult } from './curly'
 
-// those are only for documentation purposes
-// export { Easy } from './Easy.doc'
-// export { Multi } from './Multi.doc'
-// export { Share } from './Share.doc'
-// export { curly, CurlyResult } from './curly.doc'
-
 // enums
 export * from './enum/CurlAuth'
 export * from './enum/CurlChunk'
@@ -46,6 +44,7 @@ export * from './enum/CurlSslOpt'
 export * from './enum/CurlSslVersion'
 export * from './enum/CurlTimeCond'
 export * from './enum/CurlUseSsl'
+export * from './enum/CurlVersion'
 export * from './enum/CurlWriteFunc'
 export * from './enum/SocketState'
 
diff --git a/lib/mergeChunks.ts b/lib/mergeChunks.ts
@@ -7,6 +7,8 @@
 /**
  * This function is used to merge the buffers
  *  that were stored while the request was being processed.
+ *
+ * @internal
  */
 export function mergeChunks(chunks: Buffer[], length: number) {
   // We init the whole buffer below, so no need to use, the slower, Buffer.alloc
diff --git a/lib/parseHeaders.ts b/lib/parseHeaders.ts
@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 /**
+ * Whe data parsing is enabled on the {@link "Curl".Curl} instance, the headers parameter passed
+ *  to the `end` event's callback will be one array of this type.
  * @public
  */
 export type HeaderInfo = {
@@ -20,6 +22,8 @@ export type HeaderInfo = {
 /**
  * Parses the headers that were stored while
  *  the request was being processed.
+ *
+ * @internal
  */
 export function parseHeaders(headersString: string): HeaderInfo[] {
   const headers = headersString.split(/\r?\n|\r/g)
diff --git a/lib/types/CurlNativeBinding.ts b/lib/types/CurlNativeBinding.ts
@@ -10,6 +10,11 @@ import { CurlInfo } from '../generated/CurlInfo'
 import { CurlOption } from '../generated/CurlOption'
 import { MultiOption } from '../generated/MultiOption'
 
+/**
+ * This is the internal `Curl` object exported by the addon. It's not available for library users directly.
+ *
+ * @internal
+ */
 export declare interface CurlNativeBindingObject {
   globalInit(flags: CurlGlobalInit): number
   globalCleanup(): void
diff --git a/lib/types/CurlVersionInfoNativeBinding.ts b/lib/types/CurlVersionInfoNativeBinding.ts
@@ -4,20 +4,109 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+
+import { CurlVersion } from '../enum/CurlVersion'
+
+/**
+ * This is the data returned on {@link Curl.getVersionInfo| `Curl.getVersionInfo`}.
+ *
+ * It's basically the output of [`curl_version_info()`](https://curl.haxx.se/libcurl/c/curl_version_info.html)
+ */
 export declare interface CurlVersionInfoNativeBindingObject {
+  /**
+   * List of protocols supported. Example:
+   * ```json
+   * [
+   *  'dict',  'file',   'ftp',
+   *  'ftps',  'gopher', 'http',
+   *  'https', 'imap',   'imaps',
+   *  'ldap',  'ldaps',  'pop3',
+   *  'pop3s', 'rtsp',   'scp',
+   *  'sftp',  'smb',    'smbs',
+   *  'smtp',  'smtps',  'telnet',
+   *  'tftp'
+   * ]
+   * ```
+   */
   protocols: string[]
+  /**
+   * List of features supported. Example:
+   * ```json
+   * [
+   *  'AsynchDNS', 'IDN',
+   *  'IPv6',      'Largefile',
+   *  'SSPI',      'Kerberos',
+   *  'SPNEGO',    'NTLM',
+   *  'SSL',       'libz',
+   *  'HTTP2',     'HTTPS-proxy'
+   * ]
+   * ```
+   */
   features: string[]
-  rawFeatures: number
+  /**
+   * Raw feature flags
+   */
+  rawFeatures: CurlVersion
+  /**
+   * Libcurl version. Example:
+   * ```
+   * 7.69.1-DEV
+   * ```
+   */
   version: string
+  /**
+   * Integer representation of libcurl version, created like this:
+   * ```
+   * <8 bits major number> | <8 bits minor number> | <8 bits patch number>.
+   * ```
+   * Version `7.69.1` is therefore returned as `0x074501`.
+   */
   versionNumber: number
+  /**
+   * SSL library human readable version string
+   */
   sslVersion: string
-  sslVersionNum: number
+  /**
+   * This is not used - Will always be 0
+   */
+  sslVersionNum: 0
+  /**
+   * libz human readable version string
+   */
   libzVersion: string
+  /**
+   * cares human readable version string
+   * Will be null if libcurl was not built with cares
+   */
   aresVersion: string | null
+  /**
+   * cares version number
+   * Will be null if libcurl was not built with cares
+   */
   aresVersionNumber: number
+  /**
+   * libidn human readable version string
+   * Will be null if libcurl was not built with libidn
+   */
   libidnVersion: string | null
+  /**
+   * iconv version number
+   * Will be 0 if libcurl was not built with iconv
+   */
   iconvVersionNumber: number
+  /**
+   * libssh human readable version string
+   * Will be null if libcurl was not built with libssh
+   */
   libsshVersion: string | null
+  /**
+   * brotli version number
+   * Will be 0 if libcurl was not built with brotli
+   */
   brotliVersionNumber: number
+  /**
+   * brotli human readable version string
+   * Will be null if libcurl was not built with brotli
+   */
   brotliVersion: string | null
 }
diff --git a/lib/types/EasyNativeBinding.ts b/lib/types/EasyNativeBinding.ts
diff --git a/lib/types/FileInfo.ts b/lib/types/FileInfo.ts
diff --git a/lib/types/HttpPostField.ts b/lib/types/HttpPostField.ts
diff --git a/lib/types/MultiNativeBinding.ts b/lib/types/MultiNativeBinding.ts
diff --git a/lib/types/NodeLibcurlNativeBinding.ts b/lib/types/NodeLibcurlNativeBinding.ts
diff --git a/lib/types/ShareNativeBinding.ts b/lib/types/ShareNativeBinding.ts

Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@ import { NodeLibcurlNativeBinding } from './types'`
`9`	`9`	`const bindings: NodeLibcurlNativeBinding = require('../lib/binding/node_libcurl.node')`
`10`	`10`
`11`	`11`	`/**`
`12`		`- * Easy Class`
	`12`	`+ * This is a Node.js wrapper around the binding {@link EasyNativeBinding \| native Easy class}`
`13`	`13`	`*`
`14`	`14`	`* @public`
`15`	`15`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@`
`6`	`6`	`*/`
`7`	`7`	`// https://github.com/curl/curl/blob/e1be8254534898/include/curl/curl.h#L264`
`8`	`8`	`/**`
`9`		- * Object with constants on the `FileInfo` object,
	`9`	+ * Object with constants on the {@link FileInfo \| `FileInfo`} object,
`10`	`10`	* used alongside the `CHUNK_BGN_FUNCTION` option
`11`	`11`	`*`
`12`	`12`	* `CURLFILETYPE_DEVICE_BLOCK` becomes `CurlFileType.DeviceBlock`
Original file line number	Diff line number	Diff line change
`@@ -7,7 +7,7 @@`
`7`	`7`	`// https://github.com/curl/curl/blob/e1be82545348/include/curl/curl.h#L1987`
`8`	`8`	`/**`
`9`	`9`	* Object with constants for option `RTSP_REQUEST`
`10`		`- * Only available on libcurl \>= 7.20`
	`10`	`+ * Only available on libcurl >= 7.20`
`11`	`11`	`*`
`12`	`12`	* `CURL_RTSPREQ_OPTIONS` becomes `CurlRtspRequest.Options`
`13`	`13`	`*`