docs(kit): initial documentation (#86)

.eslintrc

@@ -2,11 +2,25 @@
   "globals": {
     "NodeJS": true
   },
+  "plugins": ["jsdoc"],
   "extends": [
+    "plugin:jsdoc/recommended",
     "@nuxtjs/eslint-config-typescript"
   ],
   "rules": {
     "no-console": "off",
-    "vue/one-component-per-file": "off"
+    "vue/one-component-per-file": "off",
+    "jsdoc/require-jsdoc": "off",
+    "jsdoc/require-param": "off",
+    "jsdoc/require-returns": "off",
+    "jsdoc/require-param-type": "off"
+  },
+  "settings": {
+    "jsdoc": {
+      "tagNamePreference": {
+        "warning": "warning",
+        "note": "note"
+      }
+    }
   }
 }

package.json

@@ -23,6 +23,7 @@
     "@types/jest": "^26.0.22",
     "@types/node": "^14.14.37",
     "eslint": "^7.24.0",
+    "eslint-plugin-jsdoc": "^32.3.0",
     "jest": "^26.6.3",
     "jiti": "^1.9.1",
     "lerna": "^4.0.0",

packages/app/src/composables/data.ts

@@ -13,6 +13,7 @@ export function ensureReactive<
 
 /**
  * Returns a unique string suitable for syncing data between server and client.
+ *
  * @param nuxt (optional) A Nuxt instance
  * @param vm (optional) A Vue component - by default it will use the current instance
  */
@@ -37,6 +38,7 @@ export function useSSRRef (nuxt = useNuxt(), vm = getCurrentInstance()): string
 
 /**
  * Allows accessing reactive data that can be synced between server and client.
+ *
  * @param nuxt (optional) A Nuxt instance
  * @param vm (optional) A Vue component - by default it will use the current instance
  */
@@ -53,6 +55,7 @@ export function useData<T = Record<string, any>> (
 
 /**
  * Allows accessing reactive global data that can be synced between server and client.
+ *
  * @param nuxt - (optional) A Nuxt instance
  */
 export function useGlobalData (nuxt = useNuxt()): Record<string, any> {

packages/app/src/composables/hydrate.ts

@@ -2,6 +2,7 @@ import { useNuxt } from '@nuxt/app'
 
 /**
  * Allows full control of the hydration cycle to set and receive data from the server.
+ *
  * @param key a unique key to identify the data in the Nuxt payload
  * @param get a function that returns the value to set the initial data
  * @param set a function that will receive the data on the client-side

packages/app/src/nuxt.ts

@@ -101,6 +101,7 @@ export const setNuxtInstance = (nuxt: Nuxt | null) => {
 
 /**
  * Ensures that the setup function passed in has access to the Nuxt instance via `useNuxt`.
+ *
  * @param nuxt A Nuxt instance
  * @param setup The function to call
  */

packages/kit/src/config/env.ts

@@ -3,15 +3,37 @@ import { existsSync, promises as fsp } from 'fs'
 import dotenv from 'dotenv'
 
 export interface LoadDotEnvOptions {
+  /** The project root directory (either absolute or relative to the current working directory). */
   rootDir: string
+  /**
+   * What file to look in for environment variables (either absolute or relative
+   * to the current working directory). For example, `.env`.
+   */
   dotenvFile: string
+  /**
+   * Whether to interpolate variables within .env.
+   *
+   * @example
+   * ```env
+   * BASE_DIR="/test"
+   * # resolves to "/test/further"
+   * ANOTHER_DIR="${BASE_DIR}/further"
+   * ```
+   */
   expand: boolean
-  env: typeof process.env
+  /** An object describing environment variables (key, value pairs). */
+  env: NodeJS.ProcessEnv
 }
 
-export async function loadEnv (rootDir) {
+/**
+ * Load and interpolate environment variables into `process.env`.
+ * If you need more control (or access to the values), consider using `loadDotenv` instead
+ *
+ * @param rootDir - The project root directory (either absolute or relative to the current working directory).
+ */
+export async function loadEnv (rootDir: string) {
   // Load env
-  const env = await loalDotenv({
+  const env = await loadDotenv({
     rootDir,
     dotenvFile: '.env',
     env: process.env,
@@ -26,12 +48,13 @@ export async function loadEnv (rootDir) {
   }
 }
 
-export async function loalDotenv (opts: LoadDotEnvOptions) {
+/** Load environment variables into an object. */
+export async function loadDotenv (opts: LoadDotEnvOptions) {
   const env = Object.create(null)
 
   const dotenvFile = resolve(opts.rootDir, opts.dotenvFile)
 
-  if (await existsSync(dotenvFile)) {
+  if (existsSync(dotenvFile)) {
     const parsed = dotenv.parse(await fsp.readFile(dotenvFile, 'utf-8'))
     Object.assign(env, parsed)
   }
@@ -51,13 +74,13 @@ export async function loalDotenv (opts: LoadDotEnvOptions) {
 }
 
 // Based on https://github.com/motdotla/dotenv-expand
-function expand (target, source = {}, parse = v => v) {
-  function getValue (key) {
+function expand (target: Record<string, any>, source: Record<string, any> = {}, parse = (v: any) => v) {
+  function getValue (key: string) {
     // Source value 'wins' over target value
     return source[key] !== undefined ? source[key] : target[key]
   }
 
-  function interpolate (value, parents = []) {
+  function interpolate (value: unknown, parents: string[] = []) {
     if (typeof value !== 'string') {
       return value
     }
@@ -66,7 +89,7 @@ function expand (target, source = {}, parse = v => v) {
       const parts = /(.?)\${?([a-zA-Z0-9_:]+)?}?/g.exec(match)
       const prefix = parts[1]
 
-      let value, replacePart
+      let value, replacePart: string
 
       if (prefix === '\\') {
         replacePart = parts[0]

packages/kit/src/config/load.ts

@@ -7,9 +7,12 @@ import { NuxtOptions } from '../types/config'
 import nuxtConfigSchema from './schema'
 
 export interface LoadNuxtConfigOptions {
+  /** Your project root directory (either absolute or relative to the current working directory). */
   rootDir?: string
+  /** The path to your `nuxt.config` file (either absolute or relative to your project `rootDir`). */
   configFile?: string
-  config?: any
+  /** Any overrides to your Nuxt configuration. */
+  config?: Record<string, any>
 }
 
 export function loadNuxtConfig (opts: LoadNuxtConfigOptions): NuxtOptions {