] [--templates ]\n [--disallow-unresolved] [--help] [--format ] ") 10 | process.exit(status) 11 | } 12 | 13 | for (var i = 2; i < process.argv.length; i++) { 14 | var arg = process.argv[i] 15 | if (arg == "--name") name = process.argv[++i] 16 | else if (arg == "--main") main = process.argv[++i] 17 | else if (arg == "--templates") templates = process.argv[++i] 18 | else if (arg == "--disallow-unresolved") allowUnresolvedTypes = false 19 | else if (arg == "--format") format = process.argv[++i] 20 | else if (arg.charAt(0) != "-" && !filename) filename = arg 21 | else help(arg == "--help" ? 0 : 1) 22 | } 23 | 24 | if (!filename) help(1) 25 | 26 | console.log(build({ 27 | name, 28 | main, 29 | filename, 30 | templates, 31 | format, 32 | allowUnresolvedTypes 33 | })) 34 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (C) 2013-2021 by Marijn Haverbeke and others 2 | 3 | Permission is hereby granted, free of charge, to any person obtaining a copy 4 | of this software and associated documentation files (the "Software"), to deal 5 | in the Software without restriction, including without limitation the rights 6 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 7 | copies of the Software, and to permit persons to whom the Software is 8 | furnished to do so, subject to the following conditions: 9 | 10 | The above copyright notice and this permission notice shall be included in 11 | all copies or substantial portions of the Software. 12 | 13 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 14 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 15 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 16 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 17 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 18 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 19 | THE SOFTWARE. 20 | -------------------------------------------------------------------------------- /templates/class.html: -------------------------------------------------------------------------------- 1 | <> 2 | 3 |

4 |

5 | `<>abstract <><>` 6 | <> 7 | <>`<>`<> 8 | <> `extends <>`<> 9 | <> `<> <>` 11 | <> 12 |

13 |

14 | 15 |

16 | <> 17 | 18 |

19 | 20 | <> 21 | <> 22 | <> 23 | <> 24 | <> 25 | 26 | <> 27 | <> 28 | <> 29 | 30 | <> 31 | <><><> 32 | <> 33 | 34 | <> 35 | <><><> 36 | <> 37 | 38 | 39 | 40 |

41 | -------------------------------------------------------------------------------- /templates/markdown/define.md: -------------------------------------------------------------------------------- 1 | <> 2 | 3 | <> * <>`abstract `<><>`static `<> 4 | <> 5 | <>`new `<>**`<>`**`<>` 6 | <> 7 | **`<>`**`<>?<><>: <><>` 8 | <> 9 | <> 10 | \␤<><>`new `<>**`<>`**`<>` 11 | <> 12 | <>\␤<><>␤␤ 13 | <> 14 | <> 15 | <> 16 | <> 17 | <> 18 | < s.params.concat(item.typeParams || [])).concat([item.typeParams || []])>> 19 | <> 20 | <> 21 | <> 22 | <> 23 | <> 24 | <> 25 | <> 26 | <> 27 | <> 28 | <> 29 | <> -------------------------------------------------------------------------------- /templates/define.html: -------------------------------------------------------------------------------- 1 | <> 2 |

3 |

<>abstract <><>static <>
 4 |     <>
 5 |       <>new <><><>
 6 |     <>
 7 |       <><>⁠?<><>: <><>
 8 |     <>
 9 |

10 | <> 11 |

<>new <><><>

12 | <> 13 |

14 | 15 |

16 | <> 17 | <> 18 | <> 19 | <> 20 | <>

<><> 21 | <> 22 | <> 23 | <> 24 | < s.params.concat(item.typeParams || [])).concat([item.typeParams || []])>> 25 | <> 26 | <> 27 | <>

<><> 28 | <> 29 | <> 30 | <> 31 | <> 32 | <><> 33 |

34 | -------------------------------------------------------------------------------- /templates/markdown/type.md: -------------------------------------------------------------------------------- 1 | <> 9 | 10 | <> 11 | fn<> 12 | <> 13 | <>[] 14 | <> 15 | readonly <>[] 16 | <> 17 | [<><>, <><><>] 18 | <> 19 | <><> | <><><> 20 | <> 21 | <><> & <><><> 22 | <> 23 | <><>[<><><>]<><> 24 | <> 25 | <> extends <> ? <> : <> 26 | <> 27 | {[<> in <>]: <>} 28 | <> 29 | keyof <> 30 | <> 31 | typeof <> 32 | <> 33 | {<> 34 | <>new <><> 35 | <>, <> 36 | <> 37 | <> 38 | <><>?<>: <> 39 | <>, <> 40 | <>} 41 | <> 42 | <><> 43 | <> 44 | -------------------------------------------------------------------------------- /templates/type.html: -------------------------------------------------------------------------------- 1 | <> 9 | 10 | <> 11 | fn<> 12 | <> 13 | <>[] 14 | <> 15 | readonly <>[] 16 | <> 17 | [<><>, <><><>] 18 | <> 19 | <> 20 | <> 21 | <> <> <> 22 | < 1 && mustBreak>><> 23 | <>

<> 24 | <> 25 | <> 26 | < 1 && mustBreak>>

<> 27 | <> 28 | <><>[<><><>]<><> 29 | <> 30 | <> extends <> ? <> : <> 31 | <> 32 | <> 33 | {<>

<> 34 | [ 35 | <> in <>]: 36 | <> 37 | <>

<>} 38 | <> 39 | keyof <> 40 | <> 41 | typeof <> 42 | <> 43 | < p[1]).concat($in.signatures ? $in.signatures[0].params : []))>> 44 | {<> 45 | <>

<> 46 | <>new <><> 47 | <>, <> 48 | <>

<> 49 | <> 50 | <> 51 | <>

<> 52 | <><>⁠?<>: <> 53 | <>, <> 54 | <>

<> 55 | <>} 56 | <> 57 | <> 59 | <><> 60 | <> 61 | <><> 62 | <> 63 | <> 64 | <<> 65 | <>

<> 66 | <> 67 | <>, <> 68 | <>

<> 69 | <>> 70 | <> 71 | <> 72 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # builddocs 2 | 3 | This is a utility that transforms code documented with 4 | [getdocs](https://github.com/marijnh/getdocs-ts)-style doc comments 5 | into HTML. 6 | 7 | It exports the following values: 8 | 9 | **`build`**`: (config: Object, items: ?Object) → string` 10 | 11 | Build the documentation for a given set of files. The configuration 12 | object may have the following fields: 13 | 14 | * **`name`**`: string` The name of this module. 15 | 16 | * **`filename`**`: string` If `items` isn't given, this should point 17 | at the main filename to extract docs from. 18 | 19 | * **`main`**`: ?string` The path to the main template, which should 20 | be a Markdown file with `@itemName` placeholders where the 21 | generated docs for the documented items in the source should be 22 | inserted. builddocs will complain when the set of item placeholders 23 | does not match the set of documented items. When not given, the 24 | items will be output in the order in which they are found. 25 | 26 | * **`mainText`**`: ?string` The main template as a string. 27 | 28 | * **`anchorPrefix`**`: ?string` Can be used to override the prefix 29 | used when generating HTML anchors. Defaults to the module name with 30 | a dot after it. You can set this to the empty string to disable 31 | anchor prefixes. 32 | 33 | * **`imports`**`: ?[Object | (item: Object) → ?string]` A set of object mapping type names to 34 | URLs. Will make the library recognize the given type names and 35 | properly link them. 36 | 37 | * **`qualifiedImports`**`: ?Object>` An object mapping 38 | prefixes to imports-like objects. For example, `{foo: {bar: 39 | "http://url"}}` will map the type `foo.bar` to the given URL. 40 | 41 | * **`allowUnresolvedTypes`**`: ?bool` Determines whether running into 42 | an unknown type should raise an error. Defaults to false (do raise 43 | an error). 44 | 45 | * **`templates`**`: ?string` May be the path of a directory with 46 | additional templates to load, which should have an `.html` 47 | extension and use [Mold](https://github.com/marijnh/mold) syntax. 48 | 49 | * **`env`**`: ?Object` A set of extra values to make available as 50 | global variables in the templates. 51 | 52 | * **`markdownOptions`**`: ?Object` A set of options to pass through 53 | to [markdown-it](https://github.com/markdown-it/markdown-it). 54 | 55 | * **`extendMarkdown`**`: ?(md: MarkdownIt) → MarkdownIt` A function 56 | that adds extensions to the [markdown-it](https://github.com/markdown-it/markdown-it) 57 | instance used to render the content. 58 | 59 | * **`breakAt`**`: ?number` When given, type or property lists whose 60 | (estimated) length is equal to or greater than the given value will 61 | be wrapped in a `

` element (which can be 62 | styled with a left padding to indent it). 63 | 64 | * **`processType`**`: ?(type: Type) => ?Type` When given, types will 65 | be passed through this function before being formatted. It can 66 | return a replacement JSON structure for the type. 67 | 68 | The second parameter, `items`, can be used if the JSON data for the 69 | module has already been read. By default, `build` will read it using 70 | [`getdocs-ts`](https://github.com/marijnh/getdocs-ts). 71 | 72 | **`read`**`: (config: Object) → Object` 73 | 74 | Read types and comments from a given set of files. `config` has the 75 | same shape as the argument to `build` (though only `files` and `order` 76 | will be read by this function). 77 | 78 | The function returns the data returned by 79 | [getdocs-ts](https://github.com/marijnh/getdocs-ts), an object containing 80 | metadata for each of the items documented in the source files. 81 | 82 | **`browserImports`**`: Object` 83 | 84 | An object mapping the types available in the browser (such as 85 | `Document` and `Blob`) to their MDN URLs. Useable with the `imports` 86 | or `qualifiedImports` options. 87 | 88 | ## License 89 | 90 | This software is released under an MIT open-source license. 91 | -------------------------------------------------------------------------------- /src/builtins.js: -------------------------------------------------------------------------------- 1 | module.exports = { 2 | string: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String", 3 | bool: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean", 4 | boolean: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean", 5 | true: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean", 6 | false: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean", 7 | number: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number", 8 | object: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object", 9 | Infinity: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Infinity", 10 | "-Infinity": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Infinity", 11 | NaN: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NaN", 12 | undefined: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined", 13 | null: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null", 14 | String: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String", 15 | Boolean: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean", 16 | Number: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number", 17 | Iterator: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols", 18 | Iterable: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol", 19 | Array: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array", 20 | ReadonlyArray: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array", 21 | Object: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object", 22 | RegExp: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp", 23 | RegExpMatchArray: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match#Return_value", 24 | RegExpExecArray: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match#Return_value", 25 | Function: "https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Function", 26 | Date: "https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Date", 27 | Error: "https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Error", 28 | SyntaxError: "https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/SyntaxError", 29 | ReferenceError: "https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/ReferenceError", 30 | URIError: "https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/URIError", 31 | EvalError: "https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/EvalError", 32 | RangeError: "https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/RangeError", 33 | TypeError: "https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/TypeError", 34 | ArrayBuffer: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer", 35 | DataView: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView", 36 | Float32Array: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray", 37 | Float64Array: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray", 38 | Int16Array: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray", 39 | Int32Array: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray", 40 | Int8Array: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray", 41 | Uint16Array: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray", 42 | Uint32Array: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray", 43 | Uint8Array: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray", 44 | Uint8ClampedArray: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray", 45 | Map: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map", 46 | Promise: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise", 47 | Proxy: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy", 48 | Set: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set", 49 | Symbol: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol", 50 | WeakMap: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap", 51 | WeakSet: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet", 52 | Exclude: "https://www.typescriptlang.org/docs/handbook/utility-types.html#excludetype-union", 53 | Extract: "https://www.typescriptlang.org/docs/handbook/utility-types.html#extracttype-union", 54 | InstanceType: "https://www.typescriptlang.org/docs/handbook/utility-types.html#instancetypetype", 55 | NonNullable: "https://www.typescriptlang.org/docs/handbook/utility-types.html#nonnullabletype", 56 | Omit: "https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys", 57 | Partial: "https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype", 58 | Pick: "https://www.typescriptlang.org/docs/handbook/utility-types.html#picktype-keys", 59 | Readonly: "https://www.typescriptlang.org/docs/handbook/utility-types.html#readonlytype", 60 | Record: "https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeystype", 61 | Required: "https://www.typescriptlang.org/docs/handbook/utility-types.html#requiredtype", 62 | ReturnType: "https://www.typescriptlang.org/docs/handbook/utility-types.html#returntypetype", 63 | ThisType: "https://www.typescriptlang.org/docs/handbook/utility-types.html#thistypetype", 64 | class: false, 65 | interface: false, 66 | any: false, 67 | unknown: false, 68 | never: false, 69 | union: false, 70 | tuple: false, 71 | typeparameter: false, 72 | intersection: false, 73 | conditional: false, 74 | mapped: false 75 | } 76 | -------------------------------------------------------------------------------- /src/builddocs.js: -------------------------------------------------------------------------------- 1 | let fs = require("fs") 2 | let Mold = require("mold-template") 3 | let builtins = require("./builtins") 4 | 5 | exports.browserImports = require("./browser") 6 | 7 | exports.build = function(config, items) { 8 | if (!items) items = require("getdocs-ts").gather(config) 9 | 10 | let format = config.format || "html" 11 | let renderItem = 12 | format == "html" ? name => '

' : 13 | format == "markdown" ? (() => { 14 | let mold = loadMarkdownTemplates(config, items) 15 | return name => mold.defs.item({item: items[name], name}).replace(/[\n␤]{2}$/g, "\n") 16 | })() 17 | : null 18 | 19 | let instantiateTemplate = template => { 20 | if (format == "html") template = template.replace(/(^|\n)(@[\w\$]+\n+)*@[\w\$]+(?=$|\n)/g, "

\n$&\n") 21 | let placed = Object.create(null), problems = [] 22 | let result = template.replace(/(^|\n)@([\w\$]+)(?=$|\n)/g, function(_, before, name) { 23 | if (placed[name]) problems.push("Item " + name + " is included in doc template twice") 24 | if (!items[name]) problems.push("Unknown item " + name + " included in doc template") 25 | placed[name] = true 26 | return before + renderItem(name) 27 | }) 28 | for (let name in items) if (!placed[name]) 29 | problems.push("Item " + name + " is missing from the doc template") 30 | return {result, problems} 31 | } 32 | 33 | let main 34 | if (config.main || config.mainText) { 35 | let {problems, result} = instantiateTemplate(config.mainText || fs.readFileSync(config.main, "utf8")) 36 | if (problems.length) 37 | for (let prob of problems) console.log(prob) 38 | else 39 | main = result 40 | } 41 | if (!main) main = instantiateTemplate(Object.keys(items).map(name => "@" + name).join("\n\n")).result 42 | 43 | if (format == "markdown") { 44 | return main.replace(/␤/g, "\n") 45 | } else if (format == "html") { 46 | let mdOptions = {html: true} 47 | if (config.markdownOptions) for (let prop in config.markdownOptions) mdOptions[prop] = config.markdownOptions[prop] 48 | let markdown = require("markdown-it")(mdOptions).use(require("markdown-it-deflist")) 49 | if (config.extendMarkdown) markdown = config.extendMarkdown(markdown) 50 | let mold = loadHTMLTemplates(markdown, config, items) 51 | 52 | let doc = markdown.render(main) 53 | return doc.replace(/

<\/div>/g, function(_, name) { 54 | return mold.defs.item({item: items[name], name}) 55 | }) 56 | } 57 | } 58 | 59 | function prefix(config) { 60 | let prefix = config.anchorPrefix 61 | if (prefix == null) prefix = config.name ? config.name + "." : "" 62 | return prefix 63 | } 64 | 65 | function templateDir(mold, dir, ext) { 66 | fs.readdirSync(dir).forEach(function(filename) { 67 | let match = /^(.*?)\.(\w+)$/.exec(filename) 68 | if (match && match[2] == ext && !has(mold.defs, match[1])) 69 | mold.bake(match[1], fs.readFileSync(dir + "/" + filename, "utf8").trim()) 70 | }) 71 | } 72 | 73 | function loadHTMLTemplates(markdown, config, items) { 74 | let mold = new Mold(moldEnv(config, items)) 75 | mold.defs.markdown = function(text) { 76 | if (!text) return "" 77 | return markdown.render(config.markdownFilter ? config.markdownFilter(text) : text) 78 | } 79 | mold.defs.markdownFile = function(name) { 80 | return mold.defs.markdown(fs.readFileSync(name + ".md", "utf8")) 81 | } 82 | 83 | if (config.templates) templateDir(mold, config.templates, "html") 84 | templateDir(mold, __dirname + "/../templates", "html") 85 | 86 | return mold 87 | } 88 | 89 | function loadMarkdownTemplates(config, items) { 90 | let mold = new Mold(moldEnv(config, items)) 91 | 92 | if (config.templates) templateDir(mold, config.templates, "md") 93 | templateDir(mold, __dirname + "/../templates/markdown", "md") 94 | mold.defs.indent = function({text, depth}) { 95 | return text.trim().split("\n").map(line => /\S/.test(line) ? " ".repeat(depth) + line : "").join("\n") 96 | } 97 | 98 | return mold 99 | } 100 | 101 | function has(obj, prop) { 102 | return Object.prototype.hasOwnProperty.call(obj, prop) 103 | } 104 | 105 | function isLiteral(type) { 106 | return /^(\"|\'|-?\d)/.test(type) 107 | } 108 | 109 | function maybeLinkType(config, items, type) { 110 | let name = type.type 111 | if (type.typeParamSource) return "#" + prefix(config) + type.typeParamSource 112 | if (has(items, name) && items[name].kind != "reexport") return "#" + prefix(config) + name 113 | if (isLiteral(name)) return false 114 | let imports = config.imports, qualified = config.qualifiedImports 115 | if (imports) for (let i = 0; i < imports.length; i++) { 116 | let set = imports[i] 117 | if (typeof set == "function") { 118 | let result = set(type) 119 | if (result) return result 120 | } else if (has(set, name)) { 121 | return set[name] 122 | } 123 | } 124 | if (qualified) for (let pref in qualified) if (name.indexOf(pref + ".") == 0) { 125 | let inner = name.slice(pref.length + 1) 126 | if (has(qualified[pref], inner)) 127 | return qualified[pref][inner] 128 | } 129 | if (builtins.hasOwnProperty(name)) return builtins[name] 130 | } 131 | 132 | function moldEnv(config, items) { 133 | let env = { 134 | prefix: prefix(config), 135 | linkType: function(type) { 136 | let link = maybeLinkType(config, items, type) 137 | if (!link && link !== false && !config.allowUnresolvedTypes) 138 | throw new Error("Unknown type '" + type.type + "'" + (type.loc ? " at " + type.loc.file + ":" + type.loc.line : "")) 139 | return link 140 | }, 141 | hasDescription: function(type) { 142 | if (type.description) return true 143 | if (type.properties) for (let prop in type.properties) 144 | if (env.hasDescription(type.properties[prop])) return true 145 | if (type.params) for (let i = 0; i < type.params.length; i++) 146 | if (env.hasDescription(type.params[i])) return true 147 | if (type.returns && type.returns.description) return true 148 | return false 149 | }, 150 | breakType: function(type) { 151 | return config.breakAt != null && typeLen(type) >= config.breakAt 152 | }, 153 | processType: function(type) { 154 | return (config.processType && config.processType(type)) || type 155 | } 156 | } 157 | if (config.env) for (let prop in config.env) env[prop] = config.env[prop] 158 | return env 159 | } 160 | 161 | const typeLenMap = { 162 | union: 1, 163 | intersection: 1, 164 | tuple: 2, 165 | Array: 2, 166 | ReadonlyArray: 11, 167 | indexed: 2, 168 | conditional: 6, 169 | mapped: 10, 170 | Function: 4 171 | } 172 | 173 | // Estimate the length of a type 174 | function typeLen(type, extra = 0) { 175 | if (!type) return 0 176 | if (Array.isArray(type)) return type.reduce((compl, t, i) => compl + typeLen(t) + (i ? 2 : 0), extra) 177 | let val = extra + (typeLenMap.hasOwnProperty(type.type) ? typeLenMap[type.type] : type.type.length) 178 | if (type.kind == "parameter") val += (type.name?.length || 0) + 2 179 | val += typeLen(type.implements) + 180 | (type.default ? type.default.length + 3 : 0) + 181 | typeLen(type.typeArgs, 2) 182 | if (type.signatures) { 183 | let sig = type.signatures[0] 184 | val += typeLen(sig.params) + typeLen(sig.typeArgs, 2) + typeLen(sig.returns, 3) 185 | } 186 | if (type.properties) for (let name in type.properties) { 187 | let prop = type.properties[name] 188 | if (!prop.description) val += name.length + 2 + typeLen(prop) 189 | } 190 | return val 191 | } 192 | -------------------------------------------------------------------------------- /src/browser.js: -------------------------------------------------------------------------------- 1 | module.exports = { 2 | Node: "https://developer.mozilla.org/en/docs/DOM/Node", 3 | Element: "https://developer.mozilla.org/en/docs/DOM/Element", 4 | Text: "https://developer.mozilla.org/en/docs/DOM/Text", 5 | Document: "https://developer.mozilla.org/en/docs/DOM/document", 6 | ShadowRoot: "https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot", 7 | DocumentOrShadowRoot: "https://developer.mozilla.org/en-US/docs/Web/API/DocumentOrShadowRoot", 8 | XMLDocument: "https://developer.mozilla.org/en/docs/Parsing_and_serializing_XML", 9 | HTMLElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement", 10 | HTMLAnchorElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement", 11 | HTMLAreaElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLAreaElement", 12 | HTMLAudioElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLAudioElement", 13 | HTMLBaseElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLBaseElement", 14 | HTMLBodyElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLBodyElement", 15 | HTMLBRElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLBRElement", 16 | HTMLButtonElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLButtonElement", 17 | HTMLCanvasElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement", 18 | HTMLDataElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLDataElement", 19 | HTMLDataListElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLDataListElement", 20 | HTMLDivElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement", 21 | HTMLDListElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLDListElement", 22 | HTMLDocument: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLDocument", 23 | HTMLEmbedElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLEmbedElement", 24 | HTMLFieldSetElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLFieldSetElement", 25 | HTMLFormControlsCollection: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormControlsCollection", 26 | HTMLFormElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement", 27 | HTMLHeadElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLHeadElement", 28 | HTMLHeadingElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLHeadingElement", 29 | HTMLHRElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLHRElement", 30 | HTMLHtmlElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLHtmlElement", 31 | HTMLIFrameElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLIFrameElement", 32 | HTMLImageElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement", 33 | HTMLInputElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement", 34 | HTMLKeygenElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLKeygenElement", 35 | HTMLLabelElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement", 36 | HTMLLegendElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLLegendElement", 37 | HTMLLIElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLLIElement", 38 | HTMLLinkElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLLinkElement", 39 | HTMLMapElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLMapElement", 40 | HTMLMediaElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement", 41 | HTMLMetaElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLMetaElement", 42 | HTMLMeterElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLMeterElement", 43 | HTMLModElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLModElement", 44 | HTMLObjectElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement", 45 | HTMLOListElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLOListElement", 46 | HTMLOptGroupElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLOptGroupElement", 47 | HTMLOptionElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLOptionElement", 48 | HTMLOptionsCollection: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLOptionsCollection", 49 | HTMLOutputElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLOutputElement", 50 | HTMLParagraphElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLParagraphElement", 51 | HTMLParamElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLParamElement", 52 | HTMLPreElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLPreElement", 53 | HTMLProgressElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLProgressElement", 54 | HTMLQuoteElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLQuoteElement", 55 | HTMLScriptElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLScriptElement", 56 | HTMLSelectElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLSelectElement", 57 | HTMLSourceElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLSourceElement", 58 | HTMLSpanElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLSpanElement", 59 | HTMLStyleElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLStyleElement", 60 | HTMLTableCaptionElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLTableCaptionElement", 61 | HTMLTableCellElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLTableCellElement", 62 | HTMLTableColElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLTableColElement", 63 | HTMLTableDataCellElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLTableDataCellElement", 64 | HTMLTableElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLTableElement", 65 | HTMLTableHeaderCellElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLTableHeaderCellElement", 66 | HTMLTableRowElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLTableRowElement", 67 | HTMLTableSectionElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLTableSectionElement", 68 | HTMLTextAreaElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLTextAreaElement", 69 | HTMLTimeElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLTimeElement", 70 | HTMLTitleElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLTitleElement", 71 | HTMLTrackElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLTrackElement", 72 | HTMLUListElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLUListElement", 73 | HTMLUnknownElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLUnknownElement", 74 | HTMLVideoElement: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement", 75 | Attr: "https://developer.mozilla.org/en/docs/DOM/Attr", 76 | NodeList: "https://developer.mozilla.org/en/docs/DOM/NodeList", 77 | HTMLCollection: "https://developer.mozilla.org/en/docs/DOM/HTMLCollection", 78 | NamedNodeMap: "https://developer.mozilla.org/en/docs/DOM/NamedNodeMap", 79 | DocumentFragment: "https://developer.mozilla.org/en/docs/DOM/document.createDocumentFragment", 80 | DOMTokenList: "https://developer.mozilla.org/en/docs/DOM/DOMTokenList", 81 | XPathResult: "https://developer.mozilla.org/en/docs/XPathResult", 82 | ClientRect: "https://developer.mozilla.org/en/docs/DOM/element.getClientRects", 83 | Event: "https://developer.mozilla.org/en-US/docs/DOM/event", 84 | TouchEvent: "https://developer.mozilla.org/en/docs/DOM/Touch_events", 85 | WheelEvent: "https://developer.mozilla.org/en/docs/DOM/WheelEvent", 86 | MouseEvent: "https://developer.mozilla.org/en/docs/DOM/MouseEvent", 87 | DragEvent: "https://developer.mozilla.org/en-US/docs/Web/API/DragEvent", 88 | KeyboardEvent: "https://developer.mozilla.org/en/docs/DOM/KeyboardEvent", 89 | HashChangeEvent: "https://developer.mozilla.org/en/docs/DOM/window.onhashchange", 90 | ErrorEvent: "https://developer.mozilla.org/en/docs/DOM/DOM_event_reference/error", 91 | CustomEvent: "https://developer.mozilla.org/en/docs/DOM/Event/CustomEvent", 92 | BeforeLoadEvent: "https://developer.mozilla.org/en/docs/DOM/window", 93 | ClipboardEvent: "https://developer.mozilla.org/en-US/docs/Web/API/ClipboardEvent", 94 | WebSocket: "https://developer.mozilla.org/en/docs/WebSockets", 95 | Worker: "https://developer.mozilla.org/en/docs/DOM/Worker", 96 | FileList: "https://developer.mozilla.org/en/docs/DOM/FileList", 97 | File: "https://developer.mozilla.org/en/docs/DOM/File", 98 | Blob: "https://developer.mozilla.org/en/docs/DOM/Blob", 99 | FileReader: "https://developer.mozilla.org/en/docs/DOM/FileReader", 100 | Range: "https://developer.mozilla.org/en/docs/DOM/range.detach", 101 | XMLHttpRequest: "https://developer.mozilla.org/en/docs/DOM/XMLHttpRequest", 102 | DOMParser: "https://developer.mozilla.org/en/docs/DOM/DOMParser", 103 | FormData: "https://developer.mozilla.org/en-US/docs/Web/API/FormData", 104 | Selection: "https://developer.mozilla.org/en/docs/DOM/Selection", 105 | CanvasRenderingContext2D: "https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D", 106 | Image: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/Image", 107 | MutationRecord: "https://developer.mozilla.org/en-US/docs/Web/API/MutationRecord", 108 | MutationObserver: "https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver", 109 | HTMLElementEventMap: "https://typhonjs-typedoc.github.io/ts-lib-docs/2023/dom/interfaces/HTMLElementEventMap.html" 110 | } 111 | --------------------------------------------------------------------------------

5 | <>abstract <><> 6 | <> 7 | <><><> 8 | <> extends <><> 9 | <> <> <> 11 | <> 12 |

5 | `<>abstract <><>` 6 | <> 7 | <>`<>`<> 8 | <> `extends <>`<> 9 | <> `<> <>` 11 | <> 12 |