ts-quick-docs - npm Package Compare versions

Comparing version 0.2.3 to 0.3.0

index.js

 "use strict";
 var ts = require("typescript");
 var documentation_1 = require("./src/documentation");
-function generateDocumentation(program, options) {
-    var documention = new documentation_1.default(program, options);
-    return documention.extract();
-}
 if (!module.parent) {
@@ -15,5 +11,6 @@ var program = ts.createProgram(process.argv.slice(2), {
     });
-    var output = generateDocumentation(program);
+    var output = documentation_1.default.fromProgram(program);
     console.log(JSON.stringify(output, null, 2));
 }
-module.exports = generateDocumentation;
+module.exports = documentation_1.default.fromProgram;
+module.exports.fromFiles = documentation_1.default.fromFiles;

package.json

 {
   "name": "ts-quick-docs",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "quick TypeScript documentation extractor",
@@ -5,0 +5,0 @@ "bin": "index.js",

README.md

@@ -15,3 +15,3 @@ # ts-quick-docs
 
-**CLI**
+#### CLI
 
@@ -21,18 +21,44 @@ 1. `ts-quick-docs [path/to/file.ts]... > interfaces.json`
 
-**Node API**
+#### Node API
 
+##### From TypeScript program:
+
 ```js
 const ts = require("typescript");
-const program = ts.createProject(files, options);
+const program = ts.createProgram(files, compilerOptions);
 
 const tsdoc = require("ts-quick-docs");
 const documentation = tsdoc(program, { /* options */ });
+// documentation is an array of IDocEntry items
 fs.writeFileSync("interfaces.json", JSON.stringify(documentation, null, 4));
 ```
 
+##### From set of files:
+
+```js
+const tsdoc = require("ts-quick-docs");
+const documentation = tsdoc.fromFiles(files, compilerOptions, { /* options */ });
+// documentation is an array of IDocEntry items
+fs.writeFileSync("interfaces.json", JSON.stringify(documentation, null, 4));
+```
+
+_Note that `files` must be an array but it can contain just the entry file if it imports others. A dummy TS program is created internally so we'll walk that tree for you._
+
 ## Options
 
-#### ignoreDefinitions: boolean
+#### excludeNames: `(string | RegExp)[]`
 
+Array of patterns that will be matched against each entity's `name`. Matching entities will be excluded from the output.
+
+#### excludePaths: `(string | RegExp)[]`
+
+Array of patterns that will be matched against each file's path. Matching files will not be parsed and entities in those files will not appear in the output.
+
+#### ignoreDefinitions: `boolean = false`
+
 Whether to exclude `.d.ts` files from the generated documentation blob.
 Useful to ignore imported environment libraries, like `node.d.ts`.
+
+#### includeBasicTypeProperties: `boolean = false`
+
+Whether built-in properties for basic types should appear in the output (such as `String.prototype.toString`). Basic types include boolean, number, string, and arrays of those three. Defaults to `false` because these properties tend to pollute output for no benefit.

src/documentation.d.ts

 import * as ts from "typescript";
 import { IInterfaceEntry } from "./interfaces";
 export interface IDocumentationOptions {
+    excludeNames?: (string | RegExp)[];
+    excludePaths?: (string | RegExp)[];
     ignoreDefinitions?: boolean;
+    includeBasicTypeProperties?: boolean;
 }
@@ -19,3 +22,5 @@ export default class Documentation {
     private serializeVariable(symbol, fileName);
-    private serializeDeclaration(symbol);
+    private serializeDeclaration;
+    private filterEntryName;
+    private shouldSkipFile(fileName);
 }

src/documentation.js

@@ -7,3 +7,13 @@ "use strict";
     function Documentation(program, options) {
+        var _this = this;
         if (options === void 0) { options = {}; }
+        this.serializeDeclaration = function (symbol) {
+            var details = _this.serializeSymbol(symbol);
+            details.optional = (symbol.flags & ts.SymbolFlags.Optional) !== 0;
+            return flags_1.resolveFlags(details);
+        };
+        this.filterEntryName = function (entry) {
+            var _a = _this.options.excludeNames, excludeNames = _a === void 0 ? [] : _a;
+            return excludeNames.every(function (pattern) { return entry.name.match(pattern) == null; });
+        };
         this.program = program;
@@ -44,3 +54,3 @@ this.options = options;
             var sourceFile = _a[_i];
-            if (this.options.ignoreDefinitions && /\.d\.ts$/.test(sourceFile.fileName)) {
+            if (this.shouldSkipFile(sourceFile.fileName)) {
                 continue;
@@ -50,3 +60,3 @@ }
         }
-        return output;
+        return output.filter(this.filterEntryName);
     };
@@ -67,3 +77,2 @@ Documentation.prototype.getFileName = function (node) {
     Documentation.prototype.serializeInterface = function (symbol, fileName) {
-        var _this = this;
         var details = {
@@ -80,4 +89,5 @@ documentation: ts.displayPartsToString(symbol.getDocumentationComment()),
         details.properties = Object.keys(symbol.members).sort().map(function (name) { return symbol.members[name]; })
-            .filter(function (symbol) { return symbol.valueDeclaration != null; })
-            .map(function (symbol) { return _this.serializeDeclaration(symbol); });
+            .filter(function (sym) { return sym.valueDeclaration != null; })
+            .map(this.serializeDeclaration)
+            .filter(this.filterEntryName);
         return details;
@@ -89,9 +99,14 @@ };
         details.fileName = fileName;
-        details.properties = this.getTypeOfSymbol(symbol).getProperties().map(function (s) { return _this.serializeSymbol(s); });
+        if (this.options.includeBasicTypeProperties || !/^(boolean|number|string)(\[\])?$/.test(details.type)) {
+            details.properties = this.getTypeOfSymbol(symbol).getProperties().map(function (s) { return _this.serializeSymbol(s); });
+        }
+        else {
+            details.properties = [];
+        }
         return details;
     };
-    Documentation.prototype.serializeDeclaration = function (symbol) {
-        var details = this.serializeSymbol(symbol);
-        details.optional = (symbol.flags & ts.SymbolFlags.Optional) !== 0;
-        return flags_1.resolveFlags(details);
+    Documentation.prototype.shouldSkipFile = function (fileName) {
+        var _a = this.options, excludePaths = _a.excludePaths, ignoreDefinitions = _a.ignoreDefinitions;
+        return (ignoreDefinitions && /\.d\.ts$/.test(fileName))
+            || (excludePaths != null && excludePaths.some(function (pattern) { return fileName.match(pattern) != null; }));
     };
@@ -98,0 +113,0 @@ return Documentation;

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

14366

increased by17.75%

Lines of code

327

increased by5.48%

Number of lines in readme file

63

increased by70.27%

No dependency changes