feat(napi): output Rust doc comments in definitions as jsdoc comments

examples/napi/__test__/typegen.spec.ts.md

@@ -16,8 +16,10 @@ Generated by [AVA](https://avajs.dev).
         [K: symbol]: T␊
       }␊
     }␊
+    /** This is a const */␊
     export const DEFAULT_COST: number␊
     export function getWords(): Array<string>␊
+    /** Gets some numbers */␊
     export function getNums(): Array<number>␊
     export function sumNums(nums: Array<number>): number␊
     export function readFileAsync(path: string): Promise<Buffer>␊
@@ -26,16 +28,35 @@ Generated by [AVA](https://avajs.dev).
     export function createBigInt(): BigInt␊
     export function createBigIntI64(): BigInt␊
     export function getCwd(callback: (arg0: string) => void): void␊
+    /** napi = { version = 2, features = ["serde-json"] } */␊
     export function readFile(callback: (arg0: Error | undefined, arg1?: string | undefined | null) => void): void␊
     export function eitherStringOrNumber(input: string | number): number␊
     export function returnEither(input: number): string | number␊
     export function either3(input: string | number | boolean): number␊
-    interface Obj {␊
+    export interface Obj {␊
       v: string | number␊
     }␊
     export function either4(input: string | number | boolean | Obj): number␊
-    export enum Kind { Dog = 0, Cat = 1, Duck = 2 }␊
-    export enum CustomNumEnum { One = 1, Two = 2, Three = 3, Four = 4, Six = 6, Eight = 8, Nine = 9, Ten = 10 }␊
+    /** default enum values are continuos i32s start from 0 */␊
+    export enum Kind {␊
+      /** Barks */␊
+      Dog = 0,␊
+      /** Kills birds */␊
+      Cat = 1,␊
+      /** Tasty */␊
+      Duck = 2␊
+    }␊
+    /** You could break the step and for an new continuous value. */␊
+    export enum CustomNumEnum {␊
+      One = 1,␊
+      Two = 2,␊
+      Three = 3,␊
+      Four = 4,␊
+      Six = 6,␊
+      Eight = 8,␊
+      Nine = 9,␊
+      Ten = 10␊
+    }␊
     export function enumToI32(e: CustomNumEnum): number␊
     export function throwError(): void␊
     export function createExternal(size: number): ExternalObject<number>␊
@@ -53,8 +74,10 @@ Generated by [AVA](https://avajs.dev).
     export function getUndefined(): void␊
     export function getNull(): JsNull␊
     export function asyncPlus100(p: Promise<number>): Promise<number>␊
-    interface PackageJson {␊
+    /** This is an interface for package.json */␊
+    export interface PackageJson {␊
       name: string␊
+      /** The version of the package */␊
       version: string␊
       dependencies?: Record<string, any> | undefined | null␊
       devDependencies?: Record<string, any> | undefined | null␊
@@ -73,22 +96,34 @@ Generated by [AVA](https://avajs.dev).
     export function threadsafeFunctionThrowError(cb: (...args: any[]) => any): void␊
     export function threadsafeFunctionFatalMode(cb: (...args: any[]) => any): void␊
     export function getBuffer(): Buffer␊
+    /**␊
+     * \`constructor\` option for \`struct\` requires all fields to be public,␊
+     * otherwise tag impl fn as constructor␊
+     * #[napi(constructor)]␊
+     */␊
     export class Animal {␊
+      /** Kind of animal */␊
       readonly kind: Kind␊
+      /** This is the constructor */␊
       constructor(kind: Kind, name: string)␊
+      /** This is a factory method */␊
       static withKind(kind: Kind): Animal␊
       get name(): string␊
       set name(name: string)␊
+      /**␊
+       * This is a␊
+       * multi-line comment␊
+       * with an emoji 🚀␊
+       */␊
       whoami(): string␊
+      /** This is static... */␊
       static getDogKind(): Kind␊
     }␊
+    /** Smoking test for type generation */␊
     export class Blake2BHasher {␊
-      ␊
       static withKey(key: Blake2bKey): Blake2BHasher␊
     }␊
-    export class Blake2BKey {␊
-      ␊
-    }␊
+    export class Blake2BKey { }␊
     export class Context {␊
       maybeNeed?: boolean | undefined | null␊
       constructor()␊
@@ -103,18 +138,18 @@ Generated by [AVA](https://avajs.dev).
     export namespace xxh3 {␊
       export const ALIGNMENT: number␊
       export function xxh3_64(input: Buffer): BigInt␊
+      /** xxh128 function */␊
       export function xxh128(input: Buffer): BigInt␊
+      /** Xxh3 class */␊
       export class Xxh3 {␊
-        ␊
         constructor()␊
+        /** update */␊
         update(input: Buffer): void␊
         digest(): BigInt␊
       }␊
-    ␊
     }␊
     export namespace xxh2 {␊
       export function xxh2Plus(a: number, b: number): number␊
       export function xxh3Xxh64Alias(input: Buffer): BigInt␊
-    ␊
     }␊
     `

examples/napi/index.d.ts

@@ -6,8 +6,10 @@ export class ExternalObject<T> {
     [K: symbol]: T
   }
 }
+/** This is a const */
 export const DEFAULT_COST: number
 export function getWords(): Array<string>
+/** Gets some numbers */
 export function getNums(): Array<number>
 export function sumNums(nums: Array<number>): number
 export function readFileAsync(path: string): Promise<Buffer>
@@ -16,16 +18,35 @@ export function bigintAdd(a: BigInt, b: BigInt): BigInt
 export function createBigInt(): BigInt
 export function createBigIntI64(): BigInt
 export function getCwd(callback: (arg0: string) => void): void
+/** napi = { version = 2, features = ["serde-json"] } */
 export function readFile(callback: (arg0: Error | undefined, arg1?: string | undefined | null) => void): void
 export function eitherStringOrNumber(input: string | number): number
 export function returnEither(input: number): string | number
 export function either3(input: string | number | boolean): number
-interface Obj {
+export interface Obj {
   v: string | number
 }
 export function either4(input: string | number | boolean | Obj): number
-export enum Kind { Dog = 0, Cat = 1, Duck = 2 }
-export enum CustomNumEnum { One = 1, Two = 2, Three = 3, Four = 4, Six = 6, Eight = 8, Nine = 9, Ten = 10 }
+/** default enum values are continuos i32s start from 0 */
+export enum Kind {
+  /** Barks */
+  Dog = 0,
+  /** Kills birds */
+  Cat = 1,
+  /** Tasty */
+  Duck = 2
+}
+/** You could break the step and for an new continuous value. */
+export enum CustomNumEnum {
+  One = 1,
+  Two = 2,
+  Three = 3,
+  Four = 4,
+  Six = 6,
+  Eight = 8,
+  Nine = 9,
+  Ten = 10
+}
 export function enumToI32(e: CustomNumEnum): number
 export function throwError(): void
 export function createExternal(size: number): ExternalObject<number>
@@ -43,8 +64,10 @@ export function getGlobal(): typeof global
 export function getUndefined(): void
 export function getNull(): JsNull
 export function asyncPlus100(p: Promise<number>): Promise<number>
-interface PackageJson {
+/** This is an interface for package.json */
+export interface PackageJson {
   name: string
+  /** The version of the package */
   version: string
   dependencies?: Record<string, any> | undefined | null
   devDependencies?: Record<string, any> | undefined | null
@@ -63,22 +86,34 @@ export function callThreadsafeFunction(callback: (...args: any[]) => any): void
 export function threadsafeFunctionThrowError(cb: (...args: any[]) => any): void
 export function threadsafeFunctionFatalMode(cb: (...args: any[]) => any): void
 export function getBuffer(): Buffer
+/**
+ * `constructor` option for `struct` requires all fields to be public,
+ * otherwise tag impl fn as constructor
+ * #[napi(constructor)]
+ */
 export class Animal {
+  /** Kind of animal */
   readonly kind: Kind
+  /** This is the constructor */
   constructor(kind: Kind, name: string)
+  /** This is a factory method */
   static withKind(kind: Kind): Animal
   get name(): string
   set name(name: string)
+  /**
+   * This is a
+   * multi-line comment
+   * with an emoji 🚀
+   */
   whoami(): string
+  /** This is static... */
   static getDogKind(): Kind
 }
+/** Smoking test for type generation */
 export class Blake2BHasher {
-  
   static withKey(key: Blake2bKey): Blake2BHasher
 }
-export class Blake2BKey {
-  
-}
+export class Blake2BKey { }
 export class Context {
   maybeNeed?: boolean | undefined | null
   constructor()
@@ -93,17 +128,17 @@ export class ClassWithFactory {
 export namespace xxh3 {
   export const ALIGNMENT: number
   export function xxh3_64(input: Buffer): BigInt
+  /** xxh128 function */
   export function xxh128(input: Buffer): BigInt
+  /** Xxh3 class */
   export class Xxh3 {
-    
     constructor()
+    /** update */
     update(input: Buffer): void
     digest(): BigInt
   }
-
 }
 export namespace xxh2 {
   export function xxh2Plus(a: number, b: number): number
   export function xxh3Xxh64Alias(input: Buffer): BigInt
-
 }

examples/napi/src/array.rs

@@ -4,6 +4,7 @@ fn get_words() -> Vec<&'static str> {
 }
 
 #[napi]
+/// Gets some numbers
 fn get_nums() -> Vec<u32> {
   vec![1, 1, 2, 3, 5, 8]
 }

examples/napi/src/class.rs

@@ -8,17 +8,21 @@ use crate::r#enum::Kind;
 #[napi]
 pub struct Animal {
   #[napi(readonly)]
+  /// Kind of animal
   pub kind: Kind,
+
   name: String,
 }
 
 #[napi]
 impl Animal {
+  /// This is the constructor
   #[napi(constructor)]
   pub fn new(kind: Kind, name: String) -> Self {
     Animal { kind, name }
   }
 
+  /// This is a factory method
   #[napi(factory)]
   pub fn with_kind(kind: Kind) -> Self {
     Animal {
@@ -37,6 +41,9 @@ impl Animal {
     self.name = name;
   }
 
+  /// This is a
+  /// multi-line comment
+  /// with an emoji 🚀
   #[napi]
   pub fn whoami(&self) -> String {
     match self.kind {
@@ -49,6 +56,7 @@ impl Animal {
   }
 
   #[napi]
+  /// This is static...
   pub fn get_dog_kind() -> Kind {
     Kind::Dog
   }

examples/napi/src/enum.rs

@@ -3,8 +3,11 @@ use napi::bindgen_prelude::*;
 /// default enum values are continuos i32s start from 0
 #[napi]
 pub enum Kind {
+  /// Barks
   Dog,
+  /// Kills birds
   Cat,
+  /// Tasty
   Duck,
 }
 

examples/napi/src/js_mod.rs

@@ -15,6 +15,7 @@ mod xxh3 {
   }
 
   #[napi]
+  /// xxh128 function
   pub fn xxh128(input: Buffer) -> u128 {
     let mut h: u128 = 0;
     for i in input.as_ref() {
@@ -24,6 +25,7 @@ mod xxh3 {
   }
 
   #[napi]
+  /// Xxh3 class
   pub struct Xxh3 {
     inner: BigInt,
   }
@@ -41,6 +43,7 @@ mod xxh3 {
     }
 
     #[napi]
+    /// update
     pub fn update(&mut self, input: Buffer) {
       for i in input.as_ref() {
         self.inner = BigInt {

examples/napi/src/lib.rs

@@ -4,6 +4,7 @@ extern crate napi_derive;
 extern crate serde_derive;
 
 #[napi]
+/// This is a const
 pub const DEFAULT_COST: u32 = 12;
 
 mod array;

examples/napi/src/serde.rs

@@ -4,8 +4,10 @@ use std::fs;
 
 #[napi(object)]
 #[derive(Serialize, Deserialize, Debug)]
+/// This is an interface for package.json
 struct PackageJson {
   pub name: String,
+  /// The version of the package
   pub version: String,
   pub dependencies: Option<Map<String, Value>>,
   #[serde(rename = "devDependencies")]