docs(new): migrate SecurityDetails docs to TSDoc (#6053)

puppeteer · Jun 19, 2020 · 7978315 · 7978315
1 parent 7a4170f
commit 7978315
Show file tree

Hide file tree

Showing 12 changed files with 52 additions and 31 deletions.
diff --git a/new-docs/puppeteer.accessibility.snapshot.md b/new-docs/puppeteer.accessibility.snapshot.md
@@ -22,7 +22,7 @@ snapshot(options?: SnapshotOptions): Promise<SerializedAXNode>;
 
 Promise&lt;[SerializedAXNode](./puppeteer.serializedaxnode.md)<!-- -->&gt;
 
-An AXNode object represeting the snapshot.
+An AXNode object representing the snapshot.
 
 ## Remarks
 

diff --git a/new-docs/puppeteer.md b/new-docs/puppeteer.md
@@ -30,7 +30,7 @@
 |  [Mouse](./puppeteer.mouse.md) |  |
 |  [Page](./puppeteer.page.md) | Page provides methods to interact with a single tab or \[extension background page\](https://developer.chrome.com/extensions/background\_pages) in Chromium. One \[Browser\] instance might have multiple \[Page\] instances. |
 |  [Puppeteer](./puppeteer.puppeteer.md) | The main Puppeteer class |
-|  [SecurityDetails](./puppeteer.securitydetails.md) |  |
+|  [SecurityDetails](./puppeteer.securitydetails.md) | The SecurityDetails class represents the security details of a response that was received over a secure connection. |
 |  [Target](./puppeteer.target.md) |  |
 |  [TimeoutError](./puppeteer.timeouterror.md) |  |
 |  [Touchscreen](./puppeteer.touchscreen.md) |  |

diff --git a/new-docs/puppeteer.securitydetails._constructor_.md b/new-docs/puppeteer.securitydetails._constructor_.md
diff --git a/new-docs/puppeteer.securitydetails.issuer.md b/new-docs/puppeteer.securitydetails.issuer.md
@@ -13,3 +13,5 @@ issuer(): string;
 
 string
 
+The name of the issuer of the certificate.
+
diff --git a/new-docs/puppeteer.securitydetails.md b/new-docs/puppeteer.securitydetails.md
@@ -4,17 +4,17 @@
 
 ## SecurityDetails class
 
+The SecurityDetails class represents the security details of a response that was received over a secure connection.
+
 <b>Signature:</b>
 
 ```typescript
 export declare class SecurityDetails 
 ```
 
-## Constructors
+## Remarks
 
-|  Constructor | Modifiers | Description |
-|  --- | --- | --- |
-|  [(constructor)(securityPayload)](./puppeteer.securitydetails._constructor_.md) |  | Constructs a new instance of the <code>SecurityDetails</code> class |
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `SecurityDetails` class.
 
 ## Methods
 

diff --git a/new-docs/puppeteer.securitydetails.protocol.md b/new-docs/puppeteer.securitydetails.protocol.md
@@ -13,3 +13,5 @@ protocol(): string;
 
 string
 
+The security protocol being used, e.g. "TLS 1.2".
+
diff --git a/new-docs/puppeteer.securitydetails.subjectalternativenames.md b/new-docs/puppeteer.securitydetails.subjectalternativenames.md
@@ -13,3 +13,5 @@ subjectAlternativeNames(): string[];
 
 string\[\]
 
+The list of [subject alternative names (SANs)](https://en.wikipedia.org/wiki/Subject_Alternative_Name) of the certificate.
+
diff --git a/new-docs/puppeteer.securitydetails.subjectname.md b/new-docs/puppeteer.securitydetails.subjectname.md
@@ -13,3 +13,5 @@ subjectName(): string;
 
 string
 
+The name of the subject to which the certificate was issued.
+
diff --git a/new-docs/puppeteer.securitydetails.validfrom.md b/new-docs/puppeteer.securitydetails.validfrom.md
@@ -13,3 +13,5 @@ validFrom(): number;
 
 number
 
+[Unix timestamp](https://en.wikipedia.org/wiki/Unix_time) marking the start of the certificate's validity.
+
diff --git a/new-docs/puppeteer.securitydetails.validto.md b/new-docs/puppeteer.securitydetails.validto.md
@@ -13,3 +13,5 @@ validTo(): number;
 
 number
 
+[Unix timestamp](https://en.wikipedia.org/wiki/Unix_time) marking the end of the certificate's validity.
+
diff --git a/src/common/Accessibility.ts b/src/common/Accessibility.ts
@@ -173,7 +173,7 @@ export class Accessibility {
    * }
    * ```
    *
-   * @returns An AXNode object represeting the snapshot.
+   * @returns An AXNode object representing the snapshot.
    *
    */
   public async snapshot(

diff --git a/src/common/SecurityDetails.ts b/src/common/SecurityDetails.ts
@@ -16,6 +16,12 @@
 
 import Protocol from '../protocol';
 
+/**
+ * The SecurityDetails class represents the security details of a
+ * response that was received over a secure connection.
+ *
+ * @public
+ */
 export class SecurityDetails {
   private _subjectName: string;
   private _issuer: string;
@@ -24,6 +30,9 @@ export class SecurityDetails {
   private _protocol: string;
   private _sanList: string[];
 
+  /**
+   * @internal
+   */
   constructor(securityPayload: Protocol.Network.SecurityDetails) {
     this._subjectName = securityPayload.subjectName;
     this._issuer = securityPayload.issuer;
@@ -33,26 +42,46 @@ export class SecurityDetails {
     this._sanList = securityPayload.sanList;
   }
 
-  subjectName(): string {
-    return this._subjectName;
-  }
-
+  /**
+   * @returns The name of the issuer of the certificate.
+   */
   issuer(): string {
     return this._issuer;
   }
 
+  /**
+   * @returns {@link https://en.wikipedia.org/wiki/Unix_time | Unix timestamp}
+   * marking the start of the certificate's validity.
+   */
   validFrom(): number {
     return this._validFrom;
   }
 
+  /**
+   * @returns {@link https://en.wikipedia.org/wiki/Unix_time | Unix timestamp}
+   * marking the end of the certificate's validity.
+   */
   validTo(): number {
     return this._validTo;
   }
 
+  /**
+   * @returns The security protocol being used, e.g. "TLS 1.2".
+   */
   protocol(): string {
     return this._protocol;
   }
 
+  /**
+   * @returns The name of the subject to which the certificate was issued.
+   */
+  subjectName(): string {
+    return this._subjectName;
+  }
+
+  /**
+   * @returns The list of {@link https://en.wikipedia.org/wiki/Subject_Alternative_Name | subject alternative names (SANs)} of the certificate.
+   */
   subjectAlternativeNames(): string[] {
     return this._sanList;
   }