Merge pull request #10 from schoero/development

chore(release): v0.2.0

CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## v0.2.0
+
+[compare changes](https://github.com/schoero/unwritten/compare/v0.1.4...v0.2.0)
+
+### Features
+
+- ⚠️  Render entity prefixes ([7779d37](https://github.com/schoero/unwritten/commit/7779d37))
+
+### Fixes
+
+- Don't render empty lines between nested lists ([7ed4522](https://github.com/schoero/unwritten/commit/7ed4522))
+- Unregister anonymous anchor from correct file ([ab44d76](https://github.com/schoero/unwritten/commit/ab44d76))
+- Adapt helper function to new signatures ([933f4d2](https://github.com/schoero/unwritten/commit/933f4d2))
+
+### Refactors
+
+- Improve section rendering in markdown ([6e50b90](https://github.com/schoero/unwritten/commit/6e50b90))
+
+### Build
+
+- Split pre-build and build ([b002ee6](https://github.com/schoero/unwritten/commit/b002ee6))
+
+### Chore
+
+- Add funding ([2a7257b](https://github.com/schoero/unwritten/commit/2a7257b))
+- Code cleanup ([50cc87d](https://github.com/schoero/unwritten/commit/50cc87d))
+- Code cleanup ([885ba40](https://github.com/schoero/unwritten/commit/885ba40))
+- Update dependencies ([0489074](https://github.com/schoero/unwritten/commit/0489074))
+
+#### ⚠️ Breaking Changes
+
+- ⚠️  Render entity prefixes ([7779d37](https://github.com/schoero/unwritten/commit/7779d37))
+
+### ❤️ Contributors
+
+- Roger Schönbächler
+
 ## v0.1.4
 
 [compare changes](https://github.com/schoero/unwritten/compare/v0.1.2...v0.1.4)

FUNDING.yml

@@ -0,0 +1,2 @@
+github:
+  - schoero

package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.4",
+  "version": "0.2.0",
   "type": "module",
   "name": "unwritten",
   "description": "unwritten is a cli tool that auto generates documentation from your JavaScript or TypeScript project by utilizing TSDoc or JSDoc comments.",
@@ -17,7 +17,7 @@
   "browser": "./lib/api/browser.js",
   "bin": "./lib/bin/index.js",
   "scripts": {
-    "build": "npm run typecheck && npm run lint && npm run spellcheck && npm run schema && vite build",
+    "build": "vite build",
     "build:dev": "vite build",
     "eslint": "eslint --ext .ts,.tsx,.js,.jsx,.json,.jsonc,.yml,.md ./",
     "eslint:ci": "npm run eslint -- --max-warnings 0",
@@ -31,6 +31,7 @@
     "postrelease:alpha": "npm run postrelease",
     "postrelease:beta": "npm run postrelease",
     "postrelease:latest": "eslint --fix package.json &&  markdownlint-cli2-fix 'CHANGELOG.md'",
+    "prebuild": "npm run typecheck && npm run lint && npm run spellcheck && npm run schema",
     "prerelease:alpha": "npm run test -- --run && npm run build",
     "prerelease:beta": "npm run test -- --run && npm run build",
     "prerelease:latest": "npm run test -- --run && npm run build",
@@ -67,12 +68,12 @@
     "@schoero/ts-config": "^0.3.7",
     "@schoero/vite-config": "^0.0.28",
     "@types/minimatch": "^5.1.2",
-    "@types/node": "^20.8.9",
+    "@types/node": "^20.8.10",
     "changelogen": "^0.5.5",
     "eslint-plugin-sort-exports": "^0.8.0",
     "rollup-plugin-preserve-shebang": "^1.0.1",
     "ts-json-schema-generator": "^1.4.0",
-    "vite-plugin-dts": "^3.6.2",
+    "vite-plugin-dts": "^3.6.3",
     "vite-plugin-no-bundle": "^3.0.0",
     "vitest": "^0.34.6"
   },

schemas/renderer/config.json

@@ -132,6 +132,22 @@
           ],
           "description": "Defines how properties should be encapsulated in the rendered output."
         },
+        "renderEntityPrefixes": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "const": "documentation",
+              "type": "string"
+            },
+            {
+              "const": "tableOfContents",
+              "type": "string"
+            }
+          ],
+          "description": "Defines whether the renderer should render prefixes for entities."
+        },
         "renderOrder": {
           "description": "Defines the order in which entities should be rendered.",
           "items": {
@@ -566,6 +582,22 @@
           ],
           "description": "Defines how properties should be encapsulated in the rendered output."
         },
+        "renderEntityPrefixes": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "const": "documentation",
+              "type": "string"
+            },
+            {
+              "const": "tableOfContents",
+              "type": "string"
+            }
+          ],
+          "description": "Defines whether the renderer should render prefixes for entities."
+        },
         "renderOrder": {
           "description": "Defines the order in which entities should be rendered.",
           "items": {

src/interpreter/ast/entities/function-like.ts

@@ -1,3 +1,4 @@
+import { EntityKind } from "unwritten:interpreter/enums/entity.js";
 import { withLockedSymbol } from "unwritten:interpreter/utils/ts";
 import { createSignatureEntity } from "unwritten:interpreter:ast/entities/index";
 import { getSymbolId } from "unwritten:interpreter:ast/shared/id";
@@ -35,7 +36,7 @@ export const createFunctionLikeEntity = <Kind extends FunctionLikeEntityKinds>(c
   const signatures = signatureDeclarations?.map(declaration => {
     const signature = ctx.checker.getSignatureFromDeclaration(declaration);
     assert(signature, "FunctionLike signature is not found");
-    return createSignatureEntity(ctx, signature);
+    return createSignatureEntity(ctx, signature, EntityKind.FunctionSignature);
   });
 
   const symbolId = getSymbolId(ctx, symbol);

src/interpreter/ast/entities/interface.ts

@@ -110,31 +110,31 @@ function parseInterfaceDeclaration(ctx: InterpreterContext, declaration: Interfa
   const constructSignatures = tsConstructSignatures.map(signatureDeclaration => {
     const signature = ctx.checker.getSignatureFromDeclaration(signatureDeclaration);
     assert(signature, "Construct signature not found");
-    return createSignatureEntity(ctx, signature);
+    return createSignatureEntity(ctx, signature, EntityKind.ConstructSignature);
   });
 
   const callSignatures = tsCallSignatures.map(signatureDeclaration => {
     const signature = ctx.checker.getSignatureFromDeclaration(signatureDeclaration);
     assert(signature, "Call signature not found");
-    return createSignatureEntity(ctx, signature);
+    return createSignatureEntity(ctx, signature, EntityKind.CallSignature);
   });
 
   const methodSignatures = tsMethods.map(signatureDeclaration => {
     const signature = ctx.checker.getSignatureFromDeclaration(signatureDeclaration);
     assert(signature, "Method signature not found");
-    return createSignatureEntity(ctx, signature);
+    return createSignatureEntity(ctx, signature, EntityKind.MethodSignature);
   });
 
-  const getterSignatures = tsGetters.map(signatureDeclaration => {
+  const setterSignatures = tsSetters.map(signatureDeclaration => {
     const signature = ctx.checker.getSignatureFromDeclaration(signatureDeclaration);
-    assert(signature, "Getter signature not found");
-    return createSignatureEntity(ctx, signature);
+    assert(signature, "Setter signature not found");
+    return createSignatureEntity(ctx, signature, EntityKind.SetterSignature);
   });
 
-  const setterSignatures = tsSetters.map(signatureDeclaration => {
+  const getterSignatures = tsGetters.map(signatureDeclaration => {
     const signature = ctx.checker.getSignatureFromDeclaration(signatureDeclaration);
-    assert(signature, "Setter signature not found");
-    return createSignatureEntity(ctx, signature);
+    assert(signature, "Getter signature not found");
+    return createSignatureEntity(ctx, signature, EntityKind.GetterSignature);
   });
 
   const allProperties = tsProperties.map(signature => {

src/interpreter/ast/entities/signature.test.ts

@@ -12,7 +12,7 @@ import { ts } from "unwritten:utils/template";
 import { createInterfaceEntity } from "./interface";
 
 
-scope("Interpreter", EntityKind.Signature, () => {
+scope("Interpreter", "Signature", () => {
 
   {
 
@@ -57,7 +57,7 @@ scope("Interpreter", EntityKind.Signature, () => {
     });
 
     it("should have a matching kind", () => {
-      expect(exportedFunction.signatures[0]!.kind).toBe(EntityKind.Signature);
+      expect(exportedFunction.signatures[0]!.kind).toBe(EntityKind.FunctionSignature);
     });
 
     it("should have a matching description", () => {
@@ -111,17 +111,26 @@ scope("Interpreter", EntityKind.Signature, () => {
       expect(exportedInterface.callSignatures).toHaveLength(1);
       expect(exportedInterface.constructSignatures).toHaveLength(1);
       expect(exportedInterface.methodSignatures).toHaveLength(1);
-      expect(exportedInterface.getterSignatures).toHaveLength(1);
       expect(exportedInterface.setterSignatures).toHaveLength(1);
+      expect(exportedInterface.getterSignatures).toHaveLength(1);
     });
 
     it("should have a 'declarationId' for each signature", () => {
       expect(exportedFunction.signatures[0]!.declarationId).toBeDefined();
       expect(exportedInterface.callSignatures[0]!.declarationId).toBeDefined();
       expect(exportedInterface.constructSignatures[0]!.declarationId).toBeDefined();
       expect(exportedInterface.methodSignatures[0]!.declarationId).toBeDefined();
-      expect(exportedInterface.getterSignatures[0]!.declarationId).toBeDefined();
       expect(exportedInterface.setterSignatures[0]!.declarationId).toBeDefined();
+      expect(exportedInterface.getterSignatures[0]!.declarationId).toBeDefined();
+    });
+
+    it("should have the correct kind for each signature", () => {
+      expect(exportedFunction.signatures[0]!.kind).toBe(EntityKind.FunctionSignature);
+      expect(exportedInterface.callSignatures[0]!.kind).toBe(EntityKind.CallSignature);
+      expect(exportedInterface.constructSignatures[0]!.kind).toBe(EntityKind.ConstructSignature);
+      expect(exportedInterface.methodSignatures[0]!.kind).toBe(EntityKind.MethodSignature);
+      expect(exportedInterface.setterSignatures[0]!.kind).toBe(EntityKind.SetterSignature);
+      expect(exportedInterface.getterSignatures[0]!.kind).toBe(EntityKind.GetterSignature);
     });
 
   }

src/interpreter/ast/entities/signature.ts

@@ -1,5 +1,4 @@
 import { getJSDocProperties } from "unwritten:interpreter/ast/jsdoc";
-import { EntityKind } from "unwritten:interpreter/enums/entity";
 import {
   createParameterEntity,
   createTypeParameterEntityByTypeParameter
@@ -19,11 +18,11 @@ import {
 
 import type { Signature as TSSignature, SignatureDeclaration } from "typescript";
 
-import type { SignatureEntity } from "unwritten:interpreter/type-definitions/entities";
+import type { SignatureEntity, SignatureEntityKinds } from "unwritten:interpreter/type-definitions/entities";
 import type { InterpreterContext } from "unwritten:type-definitions/context";
 
 
-export function createSignatureEntity(ctx: InterpreterContext, signature: TSSignature): SignatureEntity {
+export function createSignatureEntity(ctx: InterpreterContext, signature: TSSignature, kind: SignatureEntityKinds): SignatureEntity {
 
   // Implicit construct signatures have no declaration.
   const symbolId = signature.declaration && getSymbolIdByDeclaration(ctx, signature.declaration);
@@ -42,7 +41,6 @@ export function createSignatureEntity(ctx: InterpreterContext, signature: TSSign
   );
 
   const returnType = getReturnTypeBySignature(ctx, signature);
-  const kind = EntityKind.Signature;
 
   return {
     ...jsdocProperties,

src/interpreter/ast/types/function.ts

@@ -1,3 +1,4 @@
+import { EntityKind } from "unwritten:interpreter/enums/entity.js";
 import { TypeKind } from "unwritten:interpreter/enums/type";
 import { createSignatureEntity } from "unwritten:interpreter:ast/entities/index";
 import { getTypeId } from "unwritten:interpreter:ast/shared/id";
@@ -11,7 +12,7 @@ import type { InterpreterContext } from "unwritten:type-definitions/context";
 export function createFunctionType(ctx: InterpreterContext, type: ObjectType): FunctionType {
 
   const callSignatures = type.getCallSignatures(); // Types with constructSignatures are considered object types
-  const signatures = callSignatures.map(signature => createSignatureEntity(ctx, signature));
+  const signatures = callSignatures.map(signature => createSignatureEntity(ctx, signature, EntityKind.FunctionSignature));
   const typeId = getTypeId(ctx, type);
 
   const kind = TypeKind.Function;

src/interpreter/ast/types/object.ts

@@ -1,3 +1,4 @@
+import { EntityKind } from "unwritten:interpreter/enums/entity.js";
 import { TypeKind } from "unwritten:interpreter/enums/type";
 import {
   createGetterEntity,
@@ -43,8 +44,8 @@ export const createObjectLikeType = <SpecificObjectLikeTypeKind extends ObjectLi
   const methodProperties = tsProperties.filter(property => isMethodSymbol(ctx, property))
     .filter(method => !isSymbolExcluded(ctx, method));
 
-  const constructSignatures = tsConstructSignatures.map(signature => createSignatureEntity(ctx, signature));
-  const callSignatures = tsCallSignatures.map(signature => createSignatureEntity(ctx, signature));
+  const constructSignatures = tsConstructSignatures.map(signature => createSignatureEntity(ctx, signature, EntityKind.ConstructSignature));
+  const callSignatures = tsCallSignatures.map(signature => createSignatureEntity(ctx, signature, EntityKind.CallSignature));
 
   const methods = methodProperties.map(property => createMethodEntity(ctx, property));
   const getters = getterProperties.map(property => createGetterEntity(ctx, property));

src/interpreter/enums/entity.ts

@@ -1,22 +1,27 @@
 export enum EntityKind {
+  CallSignature = "CallSignatureEntity",
   Circular = "CircularEntity",
   Class = "ClassEntity",
+  ConstructSignature = "ConstructSignatureEntity",
   Constructor = "ConstructorEntity",
   Enum = "EnumEntity",
   EnumMember = "EnumMemberEntity",
   ExportAssignment = "ExportAssignmentEntity",
   ExportStar = "ExportDeclarationEntity",
   Function = "FunctionEntity",
+  FunctionSignature = "FunctionSignatureEntity",
   Getter = "GetterEntity",
+  GetterSignature = "GetterSignatureEntity",
   Interface = "InterfaceEntity",
   MappedTypeMember = "MappedTypeMemberEntity",
   Method = "MethodEntity",
+  MethodSignature = "MethodSignatureEntity",
   Module = "ModuleEntity",
   Namespace = "NamespaceEntity",
   Parameter = "ParameterEntity",
   Property = "PropertyEntity",
   Setter = "SetterEntity",
-  Signature = "SignatureEntity",
+  SetterSignature = "SetterSignatureEntity",
   SourceFile = "SourceFileEntity",
   TupleMember = "TupleMemberEntity",
   TypeAlias = "TypeAliasEntity",

src/interpreter/type-definitions/entities.ts

@@ -41,6 +41,7 @@ export type LinkableEntity =
   | TypeParameterEntity;
 
 export type FunctionLikeEntityKinds =
+  | EntityKind.CallSignature
   | EntityKind.Constructor
   | EntityKind.Function
   | EntityKind.Getter
@@ -54,6 +55,14 @@ export type FunctionLikeEntity =
   | MethodEntity
   | SetterEntity;
 
+export type SignatureEntityKinds =
+  | EntityKind.CallSignature
+  | EntityKind.ConstructSignature
+  | EntityKind.FunctionSignature
+  | EntityKind.GetterSignature
+  | EntityKind.MethodSignature
+  | EntityKind.SetterSignature;
+
 export type InferFunctionLikeEntityKind<Kind extends FunctionLikeEntityKinds> =
   Kind extends EntityKind.Constructor
     ? ConstructorEntity
@@ -120,7 +129,7 @@ export interface FunctionLikeEntityBase<Kind extends FunctionLikeEntityKinds> ex
 export interface FunctionEntity extends FunctionLikeEntityBase<EntityKind.Function> {
 }
 
-export interface SignatureEntity extends EntityBase<EntityKind.Signature>, JSDocProperties {
+export interface SignatureEntity extends EntityBase<SignatureEntityKinds>, JSDocProperties {
   returnType: Type & { description?: Description; } ;
   declarationId?: ID;
   modifiers?: Modifiers[];