tsdoc-markdown/dist/cjs/index.cjs.js

Generates markdown documentation from TypeScript source code.

"use strict";var x=Object.defineProperty;var V=Object.getOwnPropertyDescriptor;var H=Object.getOwnPropertyNames;var Q=Object.prototype.hasOwnProperty;var G=(t,n)=>{for(var o in n)x(t,o,{get:n[o],enumerable:!0})},W=(t,n,o,u)=>{if(n&&typeof n=="object"||typeof n=="function")for(let i of H(n))!Q.call(t,i)&&i!==o&&x(t,i,{get:()=>n[i],enumerable:!(u=V(n,i))||u.enumerable});return t};var X=t=>W(x({},"__esModule",{value:!0}),t);var sn={};G(sn,{buildDocumentation:()=>L,documentationToMarkdown:()=>v,generateDocumentation:()=>rn});module.exports=X(sn);var S=require("fs");var k=require("path/posix"),e=require("typescript"),h=({checker:t,symbol:n,doc_type:o})=>({name:n.getName(),documentation:(0,e.displayPartsToString)(n.getDocumentationComment(t)),type:t.typeToString(t.getTypeOfSymbolAtLocation(n,n.valueDeclaration)),jsDocs:n.getJsDocTags(),...o!==void 0&&{doc_type:o}}),Y=({checker:t,symbol:n,doc_type:o})=>{let{members:u}=n.valueDeclaration,i=u.map(a=>{var p;let f=(0,e.displayPartsToString)(a.symbol.getDocumentationComment(t)),y=(p=a.initializer)==null?void 0:p.getText();return{name:a.name.getText(),...y!==void 0&&{type:y},...f!==""&&{documentation:f}}});return{name:n.getName(),documentation:(0,e.displayPartsToString)(n.getDocumentationComment(t)),properties:i,jsDocs:n.getJsDocTags(),doc_type:o??"enum"}},Z=({checker:t,symbol:n})=>{let o=h({checker:t,symbol:n,doc_type:"class"}),u=t.getTypeOfSymbolAtLocation(n,n.valueDeclaration);return o.constructors=u.getConstructSignatures().map(i=>tn({checker:t,signature:i})).filter(({documentation:i})=>i!==void 0&&i!==""),o},nn=t=>{let n=(0,e.getCombinedModifierFlags)(t);return((0,e.isMethodDeclaration)(t)||(0,e.isPropertyDeclaration)(t))&&t.name.kind===e.SyntaxKind.PrivateIdentifier?!1:(n&e.ModifierFlags.Export)!==0||(n&e.ModifierFlags.Public)!==0||(0,e.isClassDeclaration)(t.parent)&&[e.ModifierFlags.None,e.ModifierFlags.Static].includes(n)},F=t=>!(0,e.isMethodDeclaration)(t)&&!(0,e.isPropertyDeclaration)(t)?void 0:((0,e.getCombinedModifierFlags)(t)&e.ModifierFlags.Static)!==0,tn=({checker:t,signature:n})=>{var u;let o={parameters:n.parameters.map(i=>h({checker:t,symbol:i})),returnType:t.typeToString(n.getReturnType()),documentation:(0,e.displayPartsToString)(n.getDocumentationComment(t))};return n.declaration!=null&&"modifiers"in n.declaration?{...o,visibility:((u=n.declaration.modifiers)==null?void 0:u[0].kind)===e.SyntaxKind.PrivateKeyword?"private":"public"}:{...o,visibility:"public"}},_=t=>(0,e.isArrowFunction)(t)?t:(0,e.forEachChild)(t,_),en=t=>[e.SyntaxKind.TypePredicate,e.SyntaxKind.TypeReference,e.SyntaxKind.FunctionType,e.SyntaxKind.ConstructorType,e.SyntaxKind.TypeQuery,e.SyntaxKind.TypeLiteral,e.SyntaxKind.ArrayType,e.SyntaxKind.TupleType,e.SyntaxKind.OptionalType,e.SyntaxKind.RestType,e.SyntaxKind.UnionType,e.SyntaxKind.IntersectionType,e.SyntaxKind.ConditionalType,e.SyntaxKind.InferType,e.SyntaxKind.ParenthesizedType,e.SyntaxKind.ThisType,e.SyntaxKind.TypeOperator,e.SyntaxKind.IndexedAccessType,e.SyntaxKind.MappedType,e.SyntaxKind.LiteralType,e.SyntaxKind.NamedTupleMember,e.SyntaxKind.TemplateLiteralType,e.SyntaxKind.ImportType].includes(t),I=t=>{if(t.parent)return(0,e.isVariableDeclaration)(t.parent)&&(0,e.isIdentifier)(t.parent.name)?t.parent.name.text:I(t.parent)},j=t=>{let{parent:n}=t;return n?n.kind===e.SyntaxKind.SourceFile||n.kind===e.SyntaxKind.ClassDeclaration?!0:n.kind===e.SyntaxKind.FunctionDeclaration||n.kind===e.SyntaxKind.FunctionExpression||n.kind===e.SyntaxKind.ArrowFunction||n.kind===e.SyntaxKind.PropertyAssignment||n.kind===e.SyntaxKind.ObjectLiteralExpression?!1:j(n):!1},N=({checker:t,node:n,types:o,...u})=>{if(!nn(n))return[];let i=[],a=({details:y,node:p})=>{i.push({...y,...C({node:p,...u})})},f=({symbol:y,doc_type:p,isStatic:s,node:l})=>{if(!y)return;let d={...h({checker:t,symbol:y,doc_type:p}),isStatic:s};a({node:l,details:d})};if((0,e.isClassDeclaration)(n)&&n.name){let y=t.getSymbolAtLocation(n.name);if(y){let p={...Z({checker:t,symbol:y}),methods:[],properties:[],...C({node:n,...u})};(0,e.forEachChild)(n,l=>{var c,m;let d=N({node:l,checker:t,types:o,...u}),r=({fileName:g,...E})=>E;(c=p.methods)==null||c.push(...d.filter(({doc_type:g})=>g==="method"||g==="function").map(r)),(m=p.properties)==null||m.push(...d.filter(({doc_type:g})=>g==="property").map(r))}),i.push(p)}}else if((0,e.isModuleDeclaration)(n))(0,e.forEachChild)(n,p=>{let s=N({node:p,checker:t,types:o,...u});i.push(...s)});else if((0,e.isMethodDeclaration)(n)){let y=t.getSymbolAtLocation(n.name),p=F(n);f({symbol:y,doc_type:"method",isStatic:p,node:n})}else if((0,e.isFunctionDeclaration)(n)){let y=t.getSymbolAtLocation(n.name??n);f({symbol:y,doc_type:"function",node:n})}else{let y=_(n),p=y!==void 0?t.getSymbolAtLocation(y.parent.name):void 0;if(y!==void 0&&p!==void 0){let s=j(y)?void 0:I(y),l=h({checker:t,symbol:p,doc_type:"function"});a({node:n,details:{...l,name:s!==void 0?`${s}.${l.name}`:l.name}})}else if((0,e.isPropertyDeclaration)(n)){let s=t.getSymbolAtLocation(n.name),l=F(n);f({symbol:s,doc_type:"property",isStatic:l,node:n})}else if((0,e.isVariableStatement)(n)){let{declarationList:{declarations:s,flags:l}}=n;if((l&e.NodeFlags.Const)!==0){let{symbol:r}=s[0];f({symbol:r,doc_type:"const",node:n})}}else if(o&&(0,e.isInterfaceDeclaration)(n)){let s=t.getSymbolAtLocation(n.name);if(s){let l=n.members.filter(r=>(0,e.isPropertySignature)(r)&&r.name!==void 0&&(0,e.isIdentifier)(r.name)).map(r=>t.getSymbolAtLocation(r.name)).filter(r=>r!==void 0).map(r=>h({checker:t,symbol:r})),d={...h({checker:t,doc_type:"interface",symbol:s}),properties:l,...C({node:n,...u})};i.push(d)}}else if(o&&(0,e.isTypeAliasDeclaration)(n)){let s=t.getSymbolAtLocation(n.name);if(s){let l=n.getChildren().find(({kind:r})=>en(r)),d={...h({checker:t,doc_type:"type",symbol:s}),...C({node:n,...u}),type:l==null?void 0:l.getText().replace(/^"|"$/g,"")};i.push(d)}}else if((0,e.isEnumDeclaration)(n)){let s=t.getSymbolAtLocation(n.name),l=Y({checker:t,symbol:s});a({node:n,details:l})}}return i},A={target:e.ScriptTarget.ES2020,module:e.ModuleKind.CommonJS,strictNullChecks:!0},C=({repo:t,node:n,sourceFile:o})=>{let{fileName:u}=o;if(t===void 0)return{fileName:u};let{url:i,branch:a}=t,{line:f}=o.getLineAndCharacterOfPosition(n.getStart()),y=(0,k.relative)(process.cwd(),o.fileName),p=`${i.replace(/\/+$/,"")}/tree/${a??"main"}/${y.replace(/^\.\.\//,"")}#L${f+1}`;return{fileName:u,url:p}},L=({inputFiles:t,options:n})=>{let{compilerOptions:o,explore:u,repo:i,types:a}=n??{explore:!1,compilerOptions:A,types:!1},f=u??!1,y=a??!1,p=(0,e.createProgram)(t,o??A),s=p.getSourceFiles(),l=t.map(m=>(0,k.resolve)(m)),d=s.filter(({isDeclarationFile:m,fileName:g})=>!m&&(f||l.includes((0,k.resolve)(g)))),r=p.getTypeChecker(),c=[];for(let m of d)(0,e.forEachChild)(m,g=>{let E=N({checker:r,node:g,sourceFile:m,repo:i,types:y});c.push(...E)});return c};var K=t=>(t??[]).map(({name:n,documentation:o})=>({name:n,documentation:o??""})),z=t=>t!==void 0&&t!==""?`: ${t}`:"",q=t=>t.map(({name:n,documentation:o})=>`* \`${n}\`${z(o)}`),R=t=>t.reduce(([n,o],u)=>[[...n,...u.isStatic!==!0?[u]:[]],[...o,...u.isStatic===!0?[u]:[]]],[[],[]]),on=({entry:t,headingLevel:n,emoji:o})=>{let{name:u,url:i,documentation:a,methods:f,properties:y,constructors:p}=t,s=[`${n}${b({emoji:o,key:"classes"})} ${u}
`];a!==void 0&&a!==""&&s.push(`${a}
`),i!==void 0&&s.push(U({emoji:o,url:i}));let l=(p??[]).filter(({visibility:D})=>D==="public");l.length>0&&(s.push(`${n}# Constructors
`),s.push(...l.map(({parameters:D,documentation:T,visibility:O})=>{let M=[`\`${O}\`${z(T)}
`];return((D==null?void 0:D.length)??0)>0&&(M.push(`Parameters:
`),M.push(...q(K(D)))),M.join(`
`)})),s.push(`
`));let d=({methods:D,titlePrefix:T})=>{((D==null?void 0:D.length)??0)!==0&&(s.push(`${n}# ${T??""}Methods
`),s.push(`${$({entries:D,emoji:o})}
`),s.push(P({entries:D??[],headingLevel:`${n}#`,docType:"Method",emoji:o})))},[r,c]=R(f??[]);d({methods:c,titlePrefix:"Static "}),d({methods:r});let m=({properties:D,titlePrefix:T})=>{((D==null?void 0:D.length)??0)!==0&&(s.push(`${n}# ${T??""}Properties
`),s.push(`${$({entries:D??[],emoji:o})}
`),s.push(P({entries:D??[],headingLevel:`${n}#`,docType:"Property",emoji:o})))},[g,E]=R(y??[]);return m({properties:E,titlePrefix:"Static "}),m({properties:g}),s.join(`
`)},J=({entry:t,headingLevel:n,emoji:o})=>{let{name:u,documentation:i}=t,a=[`${n}# ${o==null?"":":gear: "}${u}
`];return i!==void 0&&a.push(`${i}
`),a.push("| Property | Type | Description |"),a.push("| ---------- | ---------- | ---------- |"),(t.properties??[]).forEach(({name:f,type:y,documentation:p,jsDocs:s})=>{let l=(s??[]).map(({name:d,text:r})=>`${d}${r!==void 0?`: ${r.map(({text:c})=>c).join("")}`:""}`);a.push(`| \`${f}\` | \`${w(y??"")}\` | ${p!==void 0&&p!==""?w(p).replace(/\r?\n|\r/g,""):""}${l.length>0?` ${w(l.join(""))}`:""} |`)}),a.push(`
`),a.join(`
`)},U=({url:t,emoji:n})=>`[${b({emoji:n,key:"link"}).trim()}${n!=null?" ":""}Source](${t})
`,w=t=>t.split(`
`).map(n=>n.trim()).join(" ").replace(/ \| /g," or ").replace(/ & /g," and "),P=({entries:t,headingLevel:n,docType:o,emoji:u})=>{let i=p=>{let d=p.filter(({name:c})=>c==="param").map(({text:c})=>c).reduce((c,m)=>m===void 0?c:[...c,m],[]),r=c=>{var E,D;if(c.find(({kind:T,text:O})=>T==="parameterName"&&O!=="")===void 0)return;let m=((E=c.find(({kind:T})=>T==="parameterName"))==null?void 0:E.text)??"",g=((D=c.find(({kind:T})=>T==="text"))==null?void 0:D.text)??"";return{name:m,documentation:g}};return d.map(r).filter(c=>c!==void 0)},a=p=>p.filter(({name:d})=>d==="example").map(({text:d})=>d).filter(Boolean).flat(1).map(({text:d})=>d).filter(Boolean),f=t.map(({name:p,type:s,documentation:l,parameters:d,jsDocs:r,url:c})=>({name:p,type:s??"",documentation:l??"",params:[...K(d),...i(r??[])],examples:[...a(r??[])],url:c})),y=({name:p,documentation:s,type:l,params:d,examples:r,url:c})=>{let m=[`${n}# ${u==null?"":":gear: "}${p}
`];return s.length&&m.push(`${s}
`),m.push(`| ${l==="Type"?"Type alias":o} | Type |`),m.push("| ---------- | ---------- |"),m.push(`| \`${p}\` | ${l!==void 0&&l!==""?`\`${w(l)}\``:""} |
`),d.length&&(m.push(`Parameters:
`),m.push(...q(d)),m.push(`
`)),r.length&&(m.push(`Examples:
`),m.push(...r),m.push(`
`)),c!==void 0&&m.push(U({emoji:u,url:c})),m.join(`
`)};return f.map(y).join(`
`)},$=({entries:t,emoji:n})=>t.map(({name:o})=>`- [${o}](#${n==null?"":`${n.entry}-`}${o.toLowerCase().replace(/ /g,"-")})`).join(`
`),b=({emoji:t,key:n})=>t==null?"":` :${t[n]}:`,B={classes:"factory",functions:"toolbox",constants:"wrench",enum:"nut_and_bolt",entry:"gear",link:"link",interfaces:"tropical_drink",types:"cocktail"},v=({entries:t,options:n})=>{let{headingLevel:o,emoji:u}=n??{headingLevel:"##",emoji:B},i=o??"##",a=u===null?void 0:u??B,f=t.filter(({doc_type:c})=>c==="function"),y=t.filter(({doc_type:c})=>c==="class"),p=t.filter(({doc_type:c})=>c==="const"),s=t.filter(({doc_type:c})=>c==="enum"),l=t.filter(({doc_type:c})=>c==="type"),d=t.filter(({doc_type:c})=>c==="interface"),r=[];return f.length&&(r.push(`${i}${b({emoji:a,key:"functions"})} Functions
`),r.push(`${$({entries:f,emoji:a})}
`),r.push(`${P({entries:f,headingLevel:i,emoji:a,docType:"Function"})}
`)),p.length&&(r.push(`${i}${b({emoji:a,key:"constants"})} Constants
`),r.push(`${$({entries:p,emoji:a})}
`),r.push(`${P({entries:p,headingLevel:i,emoji:a,docType:"Constant"})}
`)),r.push(y.map(c=>on({entry:c,headingLevel:i,emoji:a})).join(`
`)),s.length&&(r.push(`${i}${b({emoji:a,key:"enum"})} Enum
`),r.push(`${$({entries:s,emoji:a})}
`),r.push(s.map(c=>J({entry:c,headingLevel:i,emoji:a})).join(`
`))),d.length&&(r.push(`${i}${b({emoji:a,key:"interfaces"})} Interfaces
`),r.push(`${$({entries:d,emoji:a})}
`),r.push(d.map(c=>J({entry:c,headingLevel:i,emoji:a})).join(`
`))),l.length&&(r.push(`${i}${b({emoji:a,key:"types"})} Types
`),r.push(`${$({entries:l,emoji:a})}
`),r.push(`${P({entries:l,headingLevel:i,emoji:a,docType:"Type"})}
`)),r.join(`
`)};var rn=({inputFiles:t,outputFile:n,markdownOptions:o,buildOptions:u})=>{let i=L({inputFiles:t,options:u}),a=v({entries:i,options:o});if((0,S.existsSync)(n)){let f=(0,S.readFileSync)(n,"utf-8"),y=/(<!-- TSDOC_START -->)[\s\S]*?(<!-- TSDOC_END -->)$/gm;if(f.match(y)===null){(0,S.writeFileSync)(n,a,"utf-8");return}let p=`<!-- TSDOC_START -->

${a}
<!-- TSDOC_END -->`;(0,S.writeFileSync)(n,f.replace(y,p),"utf-8");return}(0,S.writeFileSync)(n,a,"utf-8")};0&&(module.exports={buildDocumentation,documentationToMarkdown,generateDocumentation});
//# sourceMappingURL=index.cjs.js.map