From c938d5ec03c7685ff4f532f4cb6e19a8786ada52 Mon Sep 17 00:00:00 2001
From: early evening <eve@eatbigger.fish>
Date: Tue, 9 May 2023 13:55:27 -0700
Subject: [PATCH] adds some comments

---
 packages/ts-etl/src/cli.ts      | 19 ++++++++++++-------
 packages/ts-etl/src/commands.ts | 33 ++++++++++++++++++++-------------
 2 files changed, 32 insertions(+), 20 deletions(-)

diff --git a/packages/ts-etl/src/cli.ts b/packages/ts-etl/src/cli.ts
index 2a73c427..093fe986 100644
--- a/packages/ts-etl/src/cli.ts
+++ b/packages/ts-etl/src/cli.ts
@@ -4,18 +4,23 @@ import { isLeft } from 'fp-ts/lib/Either'
 import { ItemOpts, ItemCmd } from './commands'
 import { Client } from './plugins/crossref'
 
+export type PLUGIN_TYPE = 'crossref-api'
+
+const stdoutWrite = (str: string) => process.stdout.write(str)
+
 /**
- * CLI - the default export
+ * CLI
+ *
+ * the MakeCli function creates instances of the Cli,
+ * which is useful for re-use in test. The executable
+ * script for this tool will use the singleton cli
+ * (the default export).
  *
- * invoke this as a library by calling `parseAsync`--
- *   with no args, as in index.ts, it uses argv.
+ * Invoke this as a library by calling `MakeCli().parseAsync`.
+ *   with no args, as in index.ts, parseAsync uses argv.
  *   or pass in string array to parse flags.
  */
 
-export type PLUGIN_TYPE = 'crossref-api'
-
-const stdoutWrite = (str: string) => process.stdout.write(str)
-
 export function MakeCli() {
   const cli = new Command()
 
diff --git a/packages/ts-etl/src/commands.ts b/packages/ts-etl/src/commands.ts
index c3fc3c81..ebed4905 100644
--- a/packages/ts-etl/src/commands.ts
+++ b/packages/ts-etl/src/commands.ts
@@ -10,25 +10,36 @@ import type { ErrorOrDocmap } from './types'
 // .. although actually, the streaming may be a layer down instead
 export type Cmd<ArgT extends string[], OptT> = (args: ArgT, opts: OptT) => Promise<ErrorOrDocmap>
 
-// helpcmd is the one type that does not need defining
-// export const HelpCmd: Cmd<{}> = (s, opts) => {
-//   console.log(s =
-// };
-
-// export interface StreamOpts {
-//   source: 'crossref-api'
-// }
-
 export interface CrossrefConfiguration {
   preset: 'crossref-api'
   client: CrossrefClient
 }
 
+/**
+ * ItemOpts
+ *
+ * Configuration for a single Item invocation.
+ */
 export interface ItemOpts {
   source: CrossrefConfiguration
   publisher: DocmapPublisherT
 }
 
+/**
+ * ItemCmd
+ *
+ * Generates a Docmap for a single DOI. Behavior
+ * may depend on the source configuration provided.
+ */
+export const ItemCmd: Cmd<[string], ItemOpts> = ([doi], opts) => {
+  return crossref.fetchPublicationByDoi(opts.source.client, opts.publisher, doi)
+}
+
+/**
+ * PageCmd
+ *
+ * Needs implementation!
+ */
 export interface PageOpts {
   source: CrossrefConfiguration
   prefix: string
@@ -36,10 +47,6 @@ export interface PageOpts {
   pageNumber?: number
 }
 
-export const ItemCmd: Cmd<[string], ItemOpts> = ([doi], opts) => {
-  return crossref.fetchPublicationByDoi(opts.source.client, opts.publisher, doi)
-}
-
 export const PageCmd: Cmd<[], PageOpts> = async (_a, _opts) => {
   return right([])
 }