Add JSDoc comments for easier usage (#73)

* Add JSDoc comments for easier usage

* Disable default linting rules to be able to document an object
* Unfortunately we have some duplication, which we can't avoid if don't go all in on JSDoc types

* Remove doc type from prop object

* Remove added whitespace

* Fix invalid import in example

packages/web/package.json

@@ -48,6 +48,9 @@
     "extends": [
       "@vercel/eslint-config"
     ],
+    "rules": {
+      "tsdoc/syntax": "off"
+    },
     "ignorePatterns": [
       "jest.setup.ts"
     ]

packages/web/src/generic.ts

@@ -9,6 +9,16 @@ import {
   isProduction,
 } from './utils';
 
+/**
+ * Injects the Vercel Web Analytics script into the page head and starts tracking page views. Read more in our [documentation](https://vercel.com/docs/concepts/analytics/package).
+ * @param [props] - Analytics options.
+ * @param [props.mode] - The mode to use for the analytics script. Defaults to `auto`.
+ *  - `auto` - Automatically detect the environment.  Uses `production` if the environment cannot be determined.
+ *  - `production` - Always use the production script. (Sends events to the server)
+ *  - `development` - Always use the development script. (Logs events to the console)
+ * @param [props.debug] - Whether to enable debug logging in development. Defaults to `true`.
+ * @param [props.beforeSend] - A middleware function to modify events before they are sent. Should return the event object or `null` to cancel the event.
+ */
 export function inject(
   props: AnalyticsProps = {
     debug: true,
@@ -43,6 +53,12 @@ export function inject(
   document.head.appendChild(script);
 }
 
+/**
+ * Tracks a custom event. Please refer to the [documentation](https://vercel.com/docs/concepts/analytics/custom-events) for more information on custom events.
+ * @param name - The name of the event.
+ * * Examples: `Purchase`, `Click Button`, or `Play Video`.
+ * @param [properties] - Additional properties of the event. Nested objects are not supported. Allowed values are `string`, `number`, `boolean`, and `null`.
+ */
 export function track(
   name: string,
   properties?: Record<string, AllowedPropertyValues>,
@@ -82,5 +98,3 @@ export default {
   inject,
   track,
 };
-
-export type { BeforeSendEvent } from './types';

packages/web/src/react.tsx

@@ -2,6 +2,29 @@ import { useEffect } from 'react';
 import { inject, track } from './generic';
 import type { AnalyticsProps } from './types';
 
+/**
+ * Injects the Vercel Web Analytics script into the page head and starts tracking page views. Read more in our [documentation](https://vercel.com/docs/concepts/analytics/package).
+ * @param [props] - Analytics options.
+ * @param [props.mode] - The mode to use for the analytics script. Defaults to `auto`.
+ *  - `auto` - Automatically detect the environment.  Uses `production` if the environment cannot be determined.
+ *  - `production` - Always use the production script. (Sends events to the server)
+ *  - `development` - Always use the development script. (Logs events to the console)
+ * @param [props.debug] - Whether to enable debug logging in development. Defaults to `true`.
+ * @param [props.beforeSend] - A middleware function to modify events before they are sent. Should return the event object or `null` to cancel the event.
+ * @example
+ * ```js
+ * import { Analytics } from '@vercel/analytics/react';
+ *
+ * export default function App() {
+ *  return (
+ *   <div>
+ *    <Analytics />
+ *    <h1>My App</h1>
+ *  </div>
+ * );
+ * }
+ * ```
+ */
 function Analytics({
   beforeSend,
   debug = true,