Feature: Better debug output with symbol source location in various places (#159)

* Feature: Better debug output for getting symbol location in source code

* Add better debug information for parameter node parsing failures.

Author: ShukantPal

packages/webdoc-parser/src/assembler/mod-resolve-assigned-members.js

@@ -1,6 +1,11 @@
 // @flow
 
-import {type Symbol, addChildSymbol, findAccessedSymbol} from "../types/Symbol";
+import {
+  type Symbol,
+  addChildSymbol,
+  findAccessedSymbol,
+  printSourceLocation,
+} from "../types/Symbol";
 
 // This mod resolves symbols were "assigned" to another symbol parent in source code. For example,
 
@@ -68,7 +73,8 @@ export default function resolveAssignedMembersRecursive(
         console.error("{@assembly-mod resolve-assigned-members} failed to resolve these symbols: ");
 
         tryQueue.forEach((sym) => {
-          console.error(`\t ${sym.canonicalName} [to ${sym.meta.object || ""}]`);
+          console.error(`\t ${sym.canonicalName} [to ${sym.meta.object || ""}] ` +
+            printSourceLocation(sym));
         });
       }
 

packages/webdoc-parser/src/symbols-babel/build-symbol-tree.js

@@ -46,13 +46,13 @@ import {
   removeBlock,
 } from "../types/VariableRegistry";
 
+import {parserLogger, tag} from "../Logger";
 import traverse, {type NodePath} from "@babel/traverse";
 import type {LanguageConfig} from "../types/LanguageIntegration";
 import type {SourceFile} from "@webdoc/types";
 import extract from "../extract";
 import {extractParams} from "./extract-metadata";
 import extractSymbol from "./extract-symbol";
-import {parserLogger} from "../Logger";
 
 // TODO: This shouldn't really be a part of symbols-babel but rather should live with Symbol.js
 // in SymbolUtils.js
@@ -278,6 +278,11 @@ function captureSymbols(nodePath: NodePath, parent: Symbol): ?Symbol {
     for (let i = 0, j = params.length; i < j; i++) {
       declareParameter(params[i].identifier);
     }
+
+    if (params.flawed) {
+      console.error(tag.Indexer, "^^^ Errors in parsing a parameter near " +
+        fileName + ":" + (node && node.start ? node.start.line : "?"));
+    }
   } else if (node.params) {
     registerParameters(node);
   }

packages/webdoc-parser/src/symbols-babel/extract-metadata.js

@@ -116,6 +116,7 @@ import {
   createSimpleKeywordType,
 } from "@webdoc/model";
 
+import {parserLogger, tag} from "../Logger";
 import type {Symbol} from "../types/Symbol";
 
 export const mode: {
@@ -242,10 +243,13 @@ export function extractParams(
       // "", " ", "  ",  "    " or using ‌ because it is truly invisible
 
       ((params: any)).flawed = true;
-      console.error("Object patterns as parameters can't be documented");
+      parserLogger.error(tag.Indexer, "Object patterns as parameters can't be documented, at line");
+      parserLogger.warn(tag.Indexer, JSON.stringify(paramNode, null, 2));
     } else {
       ((params: any)).flawed = true;
-      console.error("Parameter node couldn't be parsed");
+      parserLogger.error(tag.Indexer, "Parameter node couldn't be parsed, " +
+          "enable warning logs for more detail");
+      parserLogger.warn(tag.Indexer, JSON.stringify(paramNode, null, 2));
     }
 
     if (param && paramTypeAnnotation) {

packages/webdoc-parser/src/transformer/transform.js

@@ -1,8 +1,8 @@
 // @flow
 
 import {type Doc, type RootDoc} from "@webdoc/types";
+import {type Symbol, printSourceLocation} from "../types/Symbol";
 import {parserLogger, tag} from "../Logger";
-import {type Symbol} from "../types/Symbol";
 import {addChildDoc} from "@webdoc/model";
 import symbolToDoc from "./symbol-to-doc";
 
@@ -18,9 +18,7 @@ export function transformRecursive(symbol: Symbol, root: RootDoc): ?Doc {
   if (!doc && !symbol.isRoot) {
     parserLogger.error(tag.DocParser,
       `Failed to parse doc for ${symbol.simpleName}(@${symbol.canonicalName || "Unnamed"})` +
-      `{@${symbol.loc.fileName || "<UNKNOWN_FILE>"}` +
-      `<${symbol.loc.start ? symbol.loc.start.line : "NaN"},` +
-      ` ${symbol.loc.start ? symbol.loc.start.column : "NaN"}>}`);
+     printSourceLocation(symbol));
     return;
   }
 

packages/webdoc-parser/src/types/Symbol.js

@@ -282,6 +282,12 @@ export function coalescePair(symbol: Symbol, pair: Symbol): Symbol {
   return symbol;
 }
 
+export function printSourceLocation(symbol: Symbol): string {
+  return `(in ${symbol.loc.fileName ?? "an unknown file"} at ` +
+    `${symbol.loc.start ? symbol.loc.start.line : "NaN"}:` +
+    `${symbol.loc.start ? symbol.loc.start.column : "NaN"})`;
+}
+
 function areEqualLoc(doc1: Symbol, doc2: Symbol): boolean {
   return doc1.loc.fileName === doc2.loc.fileName &&
     doc1.loc.start && doc2.loc.start &&