Merge pull request #3 from SoftwareBrothers/beta

docs: jsdoc monkey patches

Author: wojtek-krysiak

package.json

@@ -9,7 +9,8 @@
   "scripts": {
     "release": "semantic-release",
     "build": "tsc",
-    "lint": "eslint './src/**/*' './example-app/**/*' --ignore-pattern '*.json' --ignore-pattern 'yarn.lock'"
+    "lint": "eslint './src/**/*' './example-app/**/*' --ignore-pattern '*.json' --ignore-pattern 'yarn.lock'",
+    "check:all": "yarn lint && yarn build"
   },
   "husky": {
     "hooks": {

src/admin.module.ts

@@ -8,6 +8,17 @@ import { AbstractLoader } from './loaders/abstract.loader'
 import { AdminModuleOptions } from './interfaces/admin-module-options.interface'
 import { AdminModuleFactory } from './interfaces/admin-module-factory.interface'
 
+/**
+ * Nest module which is responsible for an AdminBro integration
+ * 
+ * @summary Nest Module
+ * 
+ * @class
+ * @name module:@admin-bro/nestjs~AdminModule
+ * @alias AdminModule
+ * @memberof module:@admin-bro/nestjs
+ */
+// This is needed by JSDoc which cannot parse this statement
 @Module({
   providers: [serveStaticProvider],
 })
@@ -19,6 +30,29 @@ export class AdminModule implements OnModuleInit {
     private readonly adminModuleOptions: AdminModuleOptions,
   ) {}
 
+  /**
+   * Creates admin in a synchronous way
+   * 
+   * @param {AdminModuleOptions} options
+   * @memberof module:@admin-bro/nestjs~AdminModule
+   * @method
+   * @name createAdmin
+   * @example
+   * import { Module } from '@nestjs/common';
+   * import { AdminModule } from '@admin-bro/nestjs';
+   * 
+   * \@Module({
+   *   imports: [
+   *     AdminModule.createAdmin({
+   *        rootPath: '/admin',
+   *        resources: [],
+   *     }),
+   *   ],
+   * })
+   * export class AppModule {}
+   * 
+   */
+  // This is needed by JSDoc which cannot parse this statement
   public static createAdmin(options: AdminModuleOptions): DynamicModule {
     return {
       module: AdminModule,
@@ -31,6 +65,38 @@ export class AdminModule implements OnModuleInit {
     }
   }
 
+  /**
+   * Creates admin in an asynchronous way
+   * 
+   * @param {AdminModuleFactory} options
+   * @memberof module:@admin-bro/nestjs~AdminModule
+   * @method
+   * @name createAdminAsync
+   * @example
+   * \@Module({
+   *   imports: [
+   *     MongooseModule.forRoot('mongodb://localhost:27017/test'),
+   *     AdminModule.createAdminAsync({
+   *       imports: [
+   *         MongooseSchemasModule, // importing module that exported model we want to inject
+   *       ],
+   *       inject: [
+   *         getModelToken('Admin'), // using mongoose function to inject dependency
+   *       ],
+   *       useFactory: (adminModel: Model<Admin>) => ({ // injected dependecy will appear as an argument
+   *         adminBroOptions: {
+   *           rootPath: '/admin',
+   *           resources: [
+   *             { resource: adminModel },
+   *           ],
+   *         },
+   *       }),
+   *     }),
+   *     MongooseSchemasModule,
+   *     ],
+   *  })
+   *  export class AppModule { }
+   */
   public static createAdminAsync(options: AdminModuleFactory): DynamicModule {
     return {
       imports: options.imports,
@@ -45,6 +111,9 @@ export class AdminModule implements OnModuleInit {
     }
   }
 
+  /**
+   * Applies given options to AdminBro and initializes it
+   */
   public onModuleInit() {
     const admin = new AdminBro(this.adminModuleOptions.adminBroOptions);
 

src/interfaces/admin-module-options.interface.ts

@@ -3,13 +3,36 @@ import { SessionOptions } from 'express-session';
 
 import { ExpressFormidableOptions } from './express-formidable-options.interface';
 
-export interface AdminModuleOptions {
+/**
+ * Options passed to nestjs module
+ * 
+ * @memberof module:@admin-bro/nestjs
+ * @alias AdminModuleOptions
+ */
+export type AdminModuleOptions = {
+  /**
+   * Standard AdminBro options
+   */
   adminBroOptions: AdminBroOptions,
+  /**
+   * Authentication options. When NOT provided, it will initialize AdminBro without login page and authorization function. 
+   */
   auth?: {
+    /**
+     * verifies if given credentials are valid, therefore if user has access to Admin Panel
+     */
     authenticate: (email: string, password: string) => Promise<CurrentAdmin>,
     cookiePassword: string,
     cookieName: string,
   }
+  /**
+   * Options passed to express formidable (used only by AdminBro express module)
+   */
   formidableOptions?: ExpressFormidableOptions,
+  /**
+   * Options passed to express session (used only by AdminBro express module)
+   * Here you might want to change the store from the default memory store to
+   * something more reliable (i.e. database).
+   */
   sessionOptions?: SessionOptions,
 }