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

Generates markdown documentation from TypeScript source code.

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

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