document everything

ngx.ts

@@ -84,6 +84,23 @@ function conform(looseNode: LooseConfigNode): ConfigNode[] {
   return [looseNode];
 }
 
+/**
+ * create nginx config nodes. behavior depends on arguments:
+ *
+ * - no args - ConfigBreak
+ * - value only - ConfigStatement
+ * - value + children - ConfigBlock
+ * - children only - ConfigFile
+ *
+ * accept strings, ConfigNodes, or nested arrays that flatten automatically.
+ *
+ * ```ts
+ * ngx() // ConfigBreak
+ * ngx("worker_processes auto") // ConfigStatement
+ * ngx("location /", ["proxy_pass http://backend"]) // ConfigBlock
+ * ngx(["server { ... }", "server { ... }"]) // ConfigFile
+ * ```
+ */
 export function ngx(value?: string, children?: LooseConfigNode[]): ConfigNode {
   const hasValue = value !== undefined && value !== "";
   const hasChildren = children !== undefined;
@@ -101,6 +118,16 @@ export function ngx(value?: string, children?: LooseConfigNode[]): ConfigNode {
   throw new Error("unreachable");
 }
 
+/**
+ * create ssl listen directives for ipv4/ipv6 with http/2 enabled.
+ *
+ * extras modify the listen directives.
+ *
+ * ```ts
+ * listen() // listen 443 ssl, listen [::]:443 ssl, http2 on
+ * listen("default_server") // includes "default_server"
+ * ```
+ */
 export const listen = (...extras: string[]) =>
   conform([
     `listen 443 ${["ssl", ...extras].join(" ")}`,
@@ -108,9 +135,25 @@ export const listen = (...extras: string[]) =>
     `http2 on`,
   ]);
 
+/**
+ * create a server_name nginx directive.
+ *
+ * ```ts
+ * serverName("example.com") // "server_name example.com;"
+ * ```
+ */
 export const serverName = (name: string) =>
   new ConfigStatement(`server_name ${name}`);
 
+/**
+ * create ssl certificate directives for let's encrypt certificates.
+ *
+ * ```ts
+ * letsEncrypt("example.com")
+ * // ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem
+ * // ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem
+ * ```
+ */
 export const letsEncrypt = (
   domain: string,
   liveDir = "/etc/letsencrypt/live",
@@ -121,6 +164,16 @@ export const letsEncrypt = (
   ]);
 
 // the default export is both the ngx function and a namespace:
+/**
+ * use as a function to create config nodes, or access helpers.
+ *
+ * ```ts
+ * import ngx from './ngx';
+ * const config = ngx("location /", ["proxy_pass http://backend"]);
+ * console.log(ngx.NGX_VERSION);
+ * const ssl = ngx.letsEncrypt("example.com");
+ * ```
+ */
 export default Object.assign(
   (value?: string, children?: LooseConfigNode[]) => ngx(value, children),
   { NGX_VERSION, listen, letsEncrypt, serverName },