more docs

Author: bryanmacfarlane

.gitignore

@@ -5,6 +5,7 @@ _test
 node/*.d.ts
 node/*.js
 node/docs/temp
+node/docs/*.js
 
 # Logs
 logs

node/docs/TypeScriptSourceToJson.ts

@@ -5,6 +5,7 @@ var path = require('path');
 
 export interface DocEntry {
     name?: string,
+    type?: string,
     documentation?: string,
     kind?: string,
     signatures?: DocEntry[],
@@ -170,8 +171,21 @@ function visit(node: ts.Node): void {
 }
 
 function getDockEntryFromSignature(signature: ts.Signature): DocEntry {
+    let paramEntries: DocEntry[] = [];
+    let params: ts.Symbol[] = signature.parameters;
+    params.forEach((ps: ts.Symbol) => {
+        let de = {} as DocEntry;
+        de.name = ps.getName();
+
+        let decls: ts.Declaration[] = ps.declarations;
+        let paramType: ts.Type = checker.getTypeAtLocation(decls[0]);
+        de.type = checker.typeToString(paramType);
+        de.documentation = ts.displayPartsToString(ps.getDocumentationComment());
+        paramEntries.push(de);
+    });
+
     let e: DocEntry = {
-        parameters: signature.parameters.map(getDockEntryFromSymbol),
+        parameters: paramEntries,
         members: {} as { string: [DocEntry]},
         return: checker.typeToString(signature.getReturnType()),
         documentation: ts.displayPartsToString(signature.getDocumentationComment())

node/docs/docs.json

@@ -30,8 +30,8 @@
                 "toolrunner.line",
                 "toolrunner.argIf",
                 "toolrunner.IExecOptions",
-                "toolrunner.ToolRunner.exec",
-                "toolrunner.ToolRunner.execSync",
+                "toolrunner.exec",
+                "toolrunner.execSync",
                 "toolrunner.pipeExecOutputToTool",
                 "toolrunner.IExecResult",
                 "task.exec",

node/docs/gendocs.ts

@@ -42,29 +42,94 @@ function anchorName(name) {
 }
 
 shell.rm('-rf', mdpath);
-var ds = docs.structure;
+var docsStructure = docs.structure;
 var aliasCache = {} as { string : [ts2json.DocEntry]};
 
-function getItem(item: string): ts2json.DocEntry {
+function getDocEntry(namespace: string): ts2json.DocEntry {
     let d: ts2json.DocEntry;
 
-    let parts: string[] =  item.split('.');
+    let parts: string[] =  namespace.split('.');
+    if (parts.length != 2) {
+        console.error(namespace + ' invalid.  doc entry must have two parts.  alias.itemName');
+    }
+
     let alias: string = parts[0];
+    let entryName: string = parts[1];
     let stmt: string = 'doc.' + docs.aliases[alias];
-
+    
     if (!aliasCache[alias]) {
         aliasCache[alias] = eval(stmt);
     }
-
-    d = aliasCache[alias];
+    d = aliasCache[alias][entryName];
 
     if (!d) {
-        console.error('Could not evaluate: ' + item + '(' + stmt + ')');
+        console.error('Could not evaluate: ' + namespace + '(' + stmt + ')');
     }
 
     return d;
 }
 
+// TODO: enums
+// TODO: isOptional on params
+// TODO: params type
+
+var writeFunction = function(name: string, item: ts2json.DocEntry) {
+    writeLine("<br/>");
+    writeLine('<div id="' + anchorName(name) + '">');
+    writeLine('### ' + name + ' <a href="#index">(^)</a>');
+
+    var sigs = item.signatures;
+    sigs.forEach((sig: ts2json.DocEntry) => {
+        // comments
+        var comment = sig.documentation;
+        if (comment) {
+            writeLine(comment);
+        }
+
+        // signature
+
+        var sigLine = item.name + '(';
+
+        if (sig.parameters) {
+            for (var i = 0; i < sig.parameters.length; i++) {
+                var param = sig.parameters[i];
+                sigLine += param.name;
+
+                // if (param.flags.isOptional) {
+                //     sigLine += '?';
+                // }
+
+                sigLine += (':' + param.type);
+
+                if (i < (sig.parameters.length - 1)) {
+                    sigLine += ', ';
+                }
+            }
+        }
+
+        sigLine += '):' + sig.return; 
+
+        writeLine('```javascript');
+        writeLine(sigLine);
+        writeLine('```');
+
+        // params table
+
+        if (sig.parameters) {
+            writeLine();
+            writeLine('Param | Type | Description');
+            writeLine('--- | --- | ---');
+            for (var i = 0; i < sig.parameters.length; i++) {
+                var param = sig.parameters[i];
+
+                var pc = param.documentation ? param.documentation || ' - ' : ' - ';
+                writeLine(param.name + ' | ' + param.type + ' | ' + pc);
+            }
+            writeLine();
+        }                       
+    });
+}
+
 writeLine('# VSTS-TASK-LIB TYPESCRIPT API');
 writeLine();
 writeLine('## Dependencies');
@@ -89,19 +154,81 @@ writeLine();
 //
 writeLine('<div id="index">');
 writeLine('## Index');
-for (var secName in ds) {
+for (var sectionName in docsStructure) {
     writeLine();
-    writeLine('### ' + secName + ' <a href="#' + anchorName(secName) + '">(v)</a>');
+    writeLine('### ' + sectionName + ' <a href="#' + anchorName(sectionName) + '">(v)</a>');
     writeLine();
 
-    var sec = ds[secName];
-    var docLabels: string[] = sec.Document as string[];
-    docLabels.forEach((docItem: string) => {
-        var item: ts2json.DocEntry  = getItem(docItem);
+    var section = docsStructure[sectionName];
+    var docItems: string[] = section.Document as string[];
+    docItems.forEach((docItem: string) => {
+        var docEntry: ts2json.DocEntry  = getDocEntry(docItem);
+
+        if (docEntry) {
+            writeLine('<a href="#' + anchorName(docItem) + '">' + docEntry.name + '</a><br/>');           
+        }
+    })
+}
+
+//
+// Docs
+//
+for (var sectionName in docsStructure) {
+    writeLine();
+    writeLine("<br/>");
+    writeLine('<div id="' + anchorName(sectionName) + '">');
+    writeLine('## ' + sectionName);
+    writeLine();
+    writeLine('---');
+    writeLine();
+
+    var sec = docsStructure[sectionName];
+    if (sec.Summary) {
+        writeLine(sec.Summary);
+    }
+
+    if (sec.Sample) {
+        try {
+            writeLine();
+            var contents = fs.readFileSync(path.join(__dirname, sec.Sample));    
+            writeLine("```javascript");
+            if (!contents || contents.length == 0) {
+                writeLine('No content');
+            }
+            writeLine(contents.toString());
+            writeLine("```");
+        }
+        catch(err) {
+            console.error(err);
+        }
+    }
+
+    var documents = sec.Document;
+    documents.forEach((docItem) => {
+        console.log('docItem', docItem);
+        var item: ts2json.DocEntry = getDocEntry(docItem);
 
         if (item) {
-            let idxTitle = docItem.substring(docItem.indexOf('.') + 1); 
-            writeLine('<a href="#' + anchorName(docItem) + '">' + idxTitle + '</a><br/>');           
+            switch (item.kind) {
+                case "Constructor":
+                case "method":
+                //case "Enumeration":
+                case "function":
+                    writeFunction(docItem, item);
+                    break;
+
+                case "interface":
+                    //writeInterface(doc, item);
+                    break;
+
+                default:
+                    console.log('warning: skipping ' + item.kind);
+                    console.log(item);
+                    process.exit();
+            }             
         }
     })
 }
+
+console.log('Done');
+