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

Generates markdown documentation from TypeScript source code.

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

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