Be more precise on the return type at summary builder

Using `this` instead of `Summary` emphasises that the instance is
mutated instead of copied and returned.

packages/core/src/summary.ts

@@ -119,9 +119,9 @@ class Summary {
    *
    * @param {SummaryWriteOptions} [options] (optional) options for write operation
    *
-   * @returns {Promise<Summary>} summary instance
+   * @returns {Promise<this>} summary instance
    */
-  async write(options?: SummaryWriteOptions): Promise<Summary> {
+  async write(options?: SummaryWriteOptions): Promise<this> {
     const overwrite = !!options?.overwrite
     const filePath = await this.filePath()
     const writeFunc = overwrite ? writeFile : appendFile
@@ -132,9 +132,9 @@ class Summary {
   /**
    * Clears the summary buffer and wipes the summary file
    *
-   * @returns {Summary} summary instance
+   * @returns {this} summary instance
    */
-  async clear(): Promise<Summary> {
+  async clear(): Promise<this> {
     return this.emptyBuffer().write({overwrite: true})
   }
 
@@ -159,9 +159,9 @@ class Summary {
   /**
    * Resets the summary buffer without writing to summary file
    *
-   * @returns {Summary} summary instance
+   * @returns {this} summary instance
    */
-  emptyBuffer(): Summary {
+  emptyBuffer(): this {
     this._buffer = ''
     return this
   }
@@ -172,9 +172,9 @@ class Summary {
    * @param {string} text content to add
    * @param {boolean} [addEOL=false] (optional) append an EOL to the raw text (default: false)
    *
-   * @returns {Summary} summary instance
+   * @returns {this} summary instance
    */
-  addRaw(text: string, addEOL = false): Summary {
+  addRaw(text: string, addEOL = false): this {
     this._buffer += text
     return addEOL ? this.addEOL() : this
   }
@@ -182,9 +182,9 @@ class Summary {
   /**
    * Adds the operating system-specific end-of-line marker to the buffer
    *
-   * @returns {Summary} summary instance
+   * @returns {this} summary instance
    */
-  addEOL(): Summary {
+  addEOL(): this {
     return this.addRaw(EOL)
   }
 
@@ -194,9 +194,9 @@ class Summary {
    * @param {string} code content to render within fenced code block
    * @param {string} lang (optional) language to syntax highlight code
    *
-   * @returns {Summary} summary instance
+   * @returns {this} summary instance
    */
-  addCodeBlock(code: string, lang?: string): Summary {
+  addCodeBlock(code: string, lang?: string): this {
     const attrs = {
       ...(lang && {lang})
     }
@@ -210,9 +210,9 @@ class Summary {
    * @param {string[]} items list of items to render
    * @param {boolean} [ordered=false] (optional) if the rendered list should be ordered or not (default: false)
    *
-   * @returns {Summary} summary instance
+   * @returns {this} summary instance
    */
-  addList(items: string[], ordered = false): Summary {
+  addList(items: string[], ordered = false): this {
     const tag = ordered ? 'ol' : 'ul'
     const listItems = items.map(item => this.wrap('li', item)).join('')
     const element = this.wrap(tag, listItems)
@@ -224,9 +224,9 @@ class Summary {
    *
    * @param {SummaryTableCell[]} rows table rows
    *
-   * @returns {Summary} summary instance
+   * @returns {this} summary instance
    */
-  addTable(rows: SummaryTableRow[]): Summary {
+  addTable(rows: SummaryTableRow[]): this {
     const tableBody = rows
       .map(row => {
         const cells = row
@@ -260,9 +260,9 @@ class Summary {
    * @param {string} label text for the closed state
    * @param {string} content collapsable content
    *
-   * @returns {Summary} summary instance
+   * @returns {this} summary instance
    */
-  addDetails(label: string, content: string): Summary {
+  addDetails(label: string, content: string): this {
     const element = this.wrap('details', this.wrap('summary', label) + content)
     return this.addRaw(element).addEOL()
   }
@@ -274,9 +274,9 @@ class Summary {
    * @param {string} alt text description of the image
    * @param {SummaryImageOptions} options (optional) addition image attributes
    *
-   * @returns {Summary} summary instance
+   * @returns {this} summary instance
    */
-  addImage(src: string, alt: string, options?: SummaryImageOptions): Summary {
+  addImage(src: string, alt: string, options?: SummaryImageOptions): this {
     const {width, height} = options || {}
     const attrs = {
       ...(width && {width}),
@@ -293,9 +293,9 @@ class Summary {
    * @param {string} text heading text
    * @param {number | string} [level=1] (optional) the heading level, default: 1
    *
-   * @returns {Summary} summary instance
+   * @returns {this} summary instance
    */
-  addHeading(text: string, level?: number | string): Summary {
+  addHeading(text: string, level?: number | string): this {
     const tag = `h${level}`
     const allowedTag = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'].includes(tag)
       ? tag
@@ -307,9 +307,9 @@ class Summary {
   /**
    * Adds an HTML thematic break (<hr>) to the summary buffer
    *
-   * @returns {Summary} summary instance
+   * @returns {this} summary instance
    */
-  addSeparator(): Summary {
+  addSeparator(): this {
     const element = this.wrap('hr', null)
     return this.addRaw(element).addEOL()
   }
@@ -317,9 +317,9 @@ class Summary {
   /**
    * Adds an HTML line break (<br>) to the summary buffer
    *
-   * @returns {Summary} summary instance
+   * @returns {this} summary instance
    */
-  addBreak(): Summary {
+  addBreak(): this {
     const element = this.wrap('br', null)
     return this.addRaw(element).addEOL()
   }
@@ -330,9 +330,9 @@ class Summary {
    * @param {string} text quote text
    * @param {string} cite (optional) citation url
    *
-   * @returns {Summary} summary instance
+   * @returns {this} summary instance
    */
-  addQuote(text: string, cite?: string): Summary {
+  addQuote(text: string, cite?: string): this {
     const attrs = {
       ...(cite && {cite})
     }
@@ -346,9 +346,9 @@ class Summary {
    * @param {string} text link text/content
    * @param {string} href hyperlink
    *
-   * @returns {Summary} summary instance
+   * @returns {this} summary instance
    */
-  addLink(text: string, href: string): Summary {
+  addLink(text: string, href: string): this {
     const element = this.wrap('a', text, {href})
     return this.addRaw(element).addEOL()
   }