@versatiles/release-tool 1.0.2 → 1.0.3

package/dist/lib/typedoc.js

@@ -17,14 +17,53 @@ function* documentProject(project) {
         throw new Error('No TypeScript code to document found! Is this a lib?');
     }
     for (const group of project.groups) {
-        for (const item of group.children) {
-            yield* documentDeclaration(item);
+        yield '\n# ' + group.title;
+        for (const declaration of group.children) {
+            switch (declaration.kind) {
+                case ReflectionKind.Class:
+                    yield* documentClass(declaration);
+                    break;
+                case ReflectionKind.Function:
+                    yield* documentMethod(declaration, 2);
+                    break;
+                case ReflectionKind.Interface:
+                    yield* documentInterface(declaration);
+                    break;
+                case ReflectionKind.TypeAlias:
+                    yield* documentType(declaration);
+                    break;
+                case ReflectionKind.Variable:
+                    yield* documentVariable(declaration);
+                    break;
+                default:
+                    throw new Error('implement ' + declaration.kind);
+            }
         }
     }
 }
-function* documentDeclaration(declaration) {
-    const declarationType = getDeclarationTypeName(declaration.kind);
-    yield `# ${declarationType}: \`${declaration.name}\`<a id="${createAnchorId(declaration)}"></a>`;
+function* documentInterface(declaration) {
+    yield `\n## Interface: \`${declaration.name}\`<a id="${createAnchorId(declaration)}"></a>`;
+    yield '\n```typescript';
+    yield 'interface {';
+    for (const child of declaration.children ?? []) {
+        if (child.kind !== ReflectionKind.Property)
+            throw Error('should be a property inside an interface');
+        if (child.type == null)
+            throw Error('should have a type');
+        const name = child.name + (child.flags.isOptional ? '?' : '');
+        yield `  ${name}: ${formatTypeDeclaration(child.type)};`;
+    }
+    yield '}';
+    yield '```';
+}
+function* documentType(declaration) {
+    yield `\n## Type: \`${declaration.name}\`<a id="${createAnchorId(declaration)}"></a>`;
+    if (declaration.type) {
+        yield `\n**Type:** <code>${formatTypeDeclaration(declaration.type)}</code>`;
+    }
+}
+function* documentClass(declaration) {
+    yield `\n## Class: \`${declaration.name}\`<a id="${createAnchorId(declaration)}"></a>`;
     yield* documentSummaryBlock(declaration);
     for (const group of declaration.groups ?? []) {
         const publicMembers = group.children.filter(member => !member.flags.isPrivate && !member.flags.isProtected);
@@ -36,30 +75,29 @@ function* documentDeclaration(declaration) {
             case 'Constructors':
                 if (publicMembers.length !== 1)
                     throw Error('publicMembers.length !== 1');
-                yield* documentMethod(publicMembers[0], true);
+                yield* documentMethod(publicMembers[0], 3, true);
+                continue;
+            case 'Accessors':
+                yield '\n### Accessors';
+                for (const member of publicMembers)
+                    yield documentAccessor(member);
                 continue;
             case 'Properties':
-                //yield '';
-                //yield '**Properties**';
+                yield '\n### Properties';
                 for (const member of publicMembers)
                     yield documentProperty(member);
                 continue;
             case 'Methods':
-                //yield '';
-                //yield '**Methods**';
                 for (const member of publicMembers)
-                    yield* documentMethod(member);
+                    yield* documentMethod(member, 3);
                 continue;
             default:
                 console.log(group);
                 throw Error('Unknown group title');
         }
     }
-    if (declaration.type) {
-        yield `\n**Type:** <code>${formatTypeDeclaration(declaration.type)}</code>`;
-    }
 }
-function* documentMethod(method, isConstructor = false) {
+function* documentMethod(method, depth, isConstructor = false) {
     if (method.signatures?.length !== 1)
         throw Error('should be 1');
     const [signature] = method.signatures;
@@ -67,8 +105,7 @@ function* documentMethod(method, isConstructor = false) {
     const parameters = formatMethodParameters(signature.parameters ?? []);
     const returnType = signature.type;
     const methodType = isConstructor ? 'Constructor' : 'Method';
-    yield `## ${methodType}: \`${methodName}(${parameters})\``;
-    yield '';
+    yield `\n${'#'.repeat(depth)} ${methodType}: \`${methodName}(${parameters})\``;
     yield* documentSummaryBlock(signature);
     if (signature.parameters && signature.parameters.length > 0) {
         yield '';
@@ -77,16 +114,15 @@ function* documentMethod(method, isConstructor = false) {
             yield documentProperty(parameter);
         }
     }
-    if (returnType) {
-        yield '';
-        yield `**Returns:** <code>${formatTypeDeclaration(returnType)}</code>`;
+    if (returnType && !isConstructor) {
+        yield `\n**Returns:** <code>${formatTypeDeclaration(returnType)}</code>`;
     }
 }
 function formatMethodParameters(parameters) {
     return parameters.map(param => param.name).join(', ');
 }
 // Helper Functions
-function getDeclarationTypeName(kind) {
+function getDeclarationKindName(kind) {
     switch (kind) {
         case ReflectionKind.Class: return 'Class';
         case ReflectionKind.Function: return 'Function';
@@ -101,13 +137,27 @@ function documentProperty(ref) {
     if (ref.flags.isOptional)
         line += ' (optional)';
     const summary = extractSummary(ref.comment);
-    if (summary)
+    if (summary != null)
+        line += '  \n    ' + summary;
+    return line;
+}
+function* documentVariable(ref) {
+    const prefix = ref.flags.isConst ? 'const' : 'let';
+    yield `\n## \`${prefix} ${ref.name}\``;
+    const summary = extractSummary(ref.comment);
+    if (summary != null)
+        yield summary;
+}
+function documentAccessor(ref) {
+    let line = `  - <code>${ref.name}${resolveTypeDeclaration(ref.type)}</code>`;
+    const summary = extractSummary(ref.comment);
+    if (summary != null)
         line += '  \n    ' + summary;
     return line;
 }
 function extractSummary(comment) {
     if (!comment)
-        return '';
+        return null;
     return comment.summary.map(line => line.text).join('');
 }
 function* documentSummaryBlock(ref) {
@@ -126,10 +176,16 @@ function* documentSummaryBlock(ref) {
             return;
         }
     }
-    yield createSourceLink(ref) + '\n';
+    const sourceLink = createSourceLink(ref);
+    if (sourceLink != null)
+        yield sourceLink;
     return;
     function formatComment(comment) {
-        return (extractSummary(comment) + ' ' + createSourceLink(ref)).replace(/\n/m, '  \n') + '\n';
+        let summary = extractSummary(comment) ?? '';
+        const link = createSourceLink(ref);
+        if (link != null)
+            summary += ' ' + link;
+        return summary.replace(/\n/m, '  \n') + '\n';
     }
 }
 function resolveTypeDeclaration(someType) {
@@ -156,36 +212,67 @@ function formatTypeDeclaration(someType) {
                         + '>';
                 return result;
             case 'reflection':
-                if (!some.declaration.signatures)
-                    throw Error('!some.declaration.signatures');
-                if (some.declaration.signatures.length !== 1)
-                    throw Error('some.declaration.signatures.length !== 1');
-                const [signature] = some.declaration.signatures;
-                const type = signature.type ? getTypeRec(signature.type) : 'void';
-                const parameters = (signature.parameters ?? [])
-                    .map(p => {
-                    return p.name + (p.type ? ': ' + getTypeRec(p.type) : '');
-                }).join(', ');
-                return `(${parameters}) => ${type}`;
+                switch (some.declaration.kind) {
+                    case ReflectionKind.TypeLiteral: return decodeReflectionTypeLiteral(some.declaration);
+                    default:
+                        console.log('declarationKindName', getDeclarationKindName(some.declaration.kind));
+                        console.dir(some, { depth: 4 });
+                        throw Error();
+                }
             case 'tuple':
                 return `[${some.elements.map(getTypeRec).join(', ')}]`;
             case 'union':
                 return some.types.map(getTypeRec).join(' | ');
+            case 'array':
+                return getTypeRec(some.elementType) + '[]';
             default:
                 console.log(some);
                 throw Error(some.type);
         }
+        function decodeReflectionTypeLiteral(ref) {
+            try {
+                if (ref.variant !== 'declaration')
+                    throw Error();
+                if (ref.groups && !ref.signatures) {
+                    if (!Array.isArray(ref.groups))
+                        throw Error();
+                    if (ref.groups.length !== 1)
+                        throw Error();
+                    const [group] = ref.groups;
+                    if (group.title !== 'Properties')
+                        throw Error();
+                    const properties = group.children.map(r => r.escapedName + ':?');
+                    return `{${properties.join(', ')}}`;
+                }
+                if (!ref.groups && ref.signatures) {
+                    if (ref.signatures.length !== 1)
+                        throw Error('ref.signatures.length !== 1');
+                    const [signature] = ref.signatures;
+                    const returnType = signature.type ? getTypeRec(signature.type) : 'void';
+                    const parameters = (signature.parameters ?? [])
+                        .map(p => {
+                        return p.name + (p.type ? ': ' + getTypeRec(p.type) : '');
+                    }).join(', ');
+                    return `(${parameters}) => ${returnType}`;
+                }
+                throw Error();
+            }
+            catch (error) {
+                console.dir(ref, { depth: 3 });
+                throw error;
+            }
+        }
     }
 }
 function createSourceLink(reference) {
     if (!reference.sources || reference.sources.length < 1)
-        return '';
+        return null;
     if (reference.sources.length > 1)
         throw Error('ref.sources.length > 1');
     const [source] = reference.sources;
     return `<sup><a href="${source.url}">[src]</a></sup>`;
 }
 function createAnchorId(reference) {
-    return `${getDeclarationTypeName(reference.kind)}_${reference.name}`.toLowerCase();
+    return `${getDeclarationKindName(reference.kind)}_${reference.name}`.toLowerCase();
 }
 //# sourceMappingURL=typedoc.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@versatiles/release-tool",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "VersaTiles release and documentation tools",
   "bin": {
     "vrt": "./dist/index.js"