docs: improve documentation and input validation

README.md

@@ -17,20 +17,31 @@ Or without installation:
 npx @mikaello/avrodoc-plus -i source -o out.html
 ```
 
-### Options
-
-- -i _sourcefolder_  
-  Pass in a source folder that will recursively parsed and crawled for avsc files
-- -o _outputfile_  
-  The file where the generated doc should be written to
-- --title _Avrodoc for ACME_  
-  The title that will be used in the generated HTML page, deafults to _Avrodoc_.
-- -s _external stylesheet less file_  
-  Your own less file, used to override specific style of your generated page
-- --ignore-invalid  
-  Ignore avsc files that can not be parsed as JSON (instead of quiting)
-
-### Enhancements
+## Options
+
+```text
+USAGE:
+    avrodoc [FLAGS] [OPTIONS] [AVRO FILES...]
+
+FLAGS:
+        --ignore-invalid     Ignore avsc files that can not be parsed as JSON (instead of quiting)
+
+OPTIONS:
+    -i, --input <folder>     Pass in a source folder that will recursively parsed and crawled for avsc files
+    -o, --output <file>      The file where the generated doc should be written to
+        --title <title>      The title that will be used in the generated HTML page, deafults to "Avrodoc".
+    -s, --style <file>       Your own less file, used to override specific style of your generated page
+
+ARGS:
+    <AVRO FILES>...          If not --input is given, you can specify individual AVRO files here
+
+EXAMPLES:
+    avrodoc --ignore-invalid --input ./schemas --output avrodoc.html --title "My First Avrodoc"
+
+    avrodoc --output avro.html --style my-styles.less avro_schema1.avsc avro_schema2.avsc avro_schema3.avsc
+```
+
+## Enhancements
 
 - support for input folders
 - support of schema/type search (search by namespace and/or schema/type)

public/js/schema.js

@@ -130,8 +130,13 @@ AvroDoc.Schema = function (avrodoc, shared_types, schema_json, filename) {
     }
   }
 
-  // Check type of object. Get all additional arbitrary attributes on the object
-  // for inclusion in the decorated schema object.
+  /**
+   * Check type of object. Get all additional arbitrary attributes on the object
+   * for inclusion in the decorated schema object.
+   *
+   * @param {object} schema
+   * @return {object} schema
+   */
   function decorateCustomAttributes(schema) {
     if (schema.annotations !== undefined && schema.annotations !== null) {
       return schema;
@@ -182,12 +187,19 @@ AvroDoc.Schema = function (avrodoc, shared_types, schema_json, filename) {
     return schema;
   }
 
-  // Takes a node in the schema tree (a JS object) and adds some fields that are useful for
-  // template rendering.
+  /**
+   * Takes a node in the schema tree (a JS object) and adds some fields that are
+   * useful for template rendering.
+   *
+   * @param {object} schema
+   * @return {object} schema
+   */
   function decorate(schema) {
     schema.filename = filename;
     schema["is_" + schema.type] = true;
-    if (schema.is_error) schema.is_record = true;
+    if (schema.is_error) {
+      schema.is_record = true;
+    }
     schema.qualified_name = qualifiedName(schema);
     schema = decorateCustomAttributes(schema);
 

src/cli.js

@@ -17,6 +17,9 @@ import arg from "arg";
 const debug = debugFn("avrodoc:cli");
 
 const argv = arg({
+  "--help": Boolean,
+  "-h": "--help",
+
   "--output": String,
   "-o": "--output",
 
@@ -31,42 +34,68 @@ const argv = arg({
   "--ignore-invalid": Boolean,
 });
 
-let inputFiles = null;
-let outputFile = null;
-let ignoreInvalidSchemas = false;
+const usage = `USAGE:
+    avrodoc [FLAGS] [OPTIONS] [AVRO FILES...]
+
+FLAGS:
+        --ignore-invalid     Ignore avsc files that can not be parsed as JSON (instead of quiting)
+
+OPTIONS:
+    -i, --input <folder>     Pass in a source folder that will recursively parsed and crawled for avsc files
+    -o, --output <file>      The file where the generated doc should be written to
+        --title <title>      The title that will be used in the generated HTML page, deafults to "Avrodoc".
+    -s, --style <file>       Your own less file, used to override specific style of your generated page
+
+ARGS:
+    <AVRO FILES>...          If not --input is given, you can specify individual AVRO files here
+
+EXAMPLES:
+    avrodoc --ignore-invalid --input ./schemas --output avrodoc.html --title "My First Avrodoc"
+
+    avrodoc --output avro.html --style my-styles.less avro_schema1.avsc avro_schema2.avsc avro_schema3.avsc
+`;
+
+if (
+  argv["--help"] ||
+  (argv._.length === 0 && Object.entries(argv).length === 1) // no params
+) {
+  console.log(usage);
+  process.exit(0);
+}
+
+let inputFiles = [];
 
-// Determine list of input files file1.avsc file2.avsc
 if (argv["--input"]) {
   debug("Collecting all avsc files from root folder ", argv["--input"]);
-  inputFiles = collectInputFiles(argv["--input"]);
-} else if (argv._.length > 0) {
-  debug("Using passed arguments as inputfiles...");
-  inputFiles = argv._;
+  inputFiles = inputFiles.concat(collectInputFiles(argv["--input"]));
 }
 
-// Determine whether an output file is specified
-if (argv["--output"]) {
-  outputFile = argv["--output"];
+if (argv._.length > 0) {
+  debug("Using passed arguments as inputfiles...");
+  inputFiles = inputFiles.concat(argv._);
 }
 
-const extra_less_files = argv["--style"] ? [argv["--style"]] : [];
-
-if (argv["--ignore-invalid"]) {
-  ignoreInvalidSchemas = true;
-}
+const outputFile = argv["--output"];
 const pageTitle = argv["--title"];
+const extraLessFile = argv["--style"];
+const ignoreInvalidSchemas = Boolean(argv["--ignore-invalid"]);
 
 //valid input?
-if (!inputFiles || inputFiles.length === 0 || outputFile === null) {
+if (inputFiles.length === 0) {
+  console.error(
+    'Missing input schemata, either specify a folder with "--input" or individual AVRO files. Specify "--help" to see usage.'
+  );
+  process.exit(1);
+} else if (outputFile == null) {
   console.error(
-    "Usage: avrodoc [-i rootfolder] [my-schema.avsc [another-schema.avsc...]] [-o my-documentation.html] [-s my-style.less] [--ignore-invalid]"
+    'Missing output file, specify with "--output" where the resulting HTML should go. Specify "--help" to see usage.'
   );
   process.exit(1);
 }
 
 createAvroDoc(
   pageTitle,
-  extra_less_files,
+  extraLessFile ? [extraLessFile] : [],
   inputFiles,
   outputFile,
   ignoreInvalidSchemas