Merge pull request #12 from schoero/development

chore(release): v0.2.2

CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## v0.2.2
+
+[compare changes](https://github.com/schoero/unwritten/compare/v0.2.0...v0.2.2)
+
+### Features
+
+- Add option to disable class member titles ([782ea1c](https://github.com/schoero/unwritten/commit/782ea1c))
+- Add option to treat default values as optional ([b522c6d](https://github.com/schoero/unwritten/commit/b522c6d))
+
+### Fixes
+
+- Use correct signature entities ([1048555](https://github.com/schoero/unwritten/commit/1048555))
+- Correct function entity kinds ([7e2c43b](https://github.com/schoero/unwritten/commit/7e2c43b))
+- Double rendering of member context ([cd2ce41](https://github.com/schoero/unwritten/commit/cd2ce41))
+
+### Chore
+
+- **release:** V0.2.1 ([1dd37d8](https://github.com/schoero/unwritten/commit/1dd37d8))
+
+### ❤️ Contributors
+
+- Roger Schönbächler
+
 ## v0.2.1
 
 [compare changes](https://github.com/schoero/unwritten/compare/v0.2.0...v0.2.1)

package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.2.1",
+  "version": "0.2.2",
   "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.",

schemas/renderer/config.json

@@ -148,6 +148,10 @@
           ],
           "description": "Defines whether the renderer should render titles for object members."
         },
+        "renderDefaultValuesAsOptional": {
+          "description": "Defines whether the renderer should render an additional optional tag for default values.",
+          "type": "boolean"
+        },
         "renderEntityPrefixes": {
           "anyOf": [
             {
@@ -614,6 +618,10 @@
           ],
           "description": "Defines whether the renderer should render titles for object members."
         },
+        "renderDefaultValuesAsOptional": {
+          "description": "Defines whether the renderer should render an additional optional tag for default values.",
+          "type": "boolean"
+        },
         "renderEntityPrefixes": {
           "anyOf": [
             {

src/renderer/markup/ast-converter/entities/parameter.test.ts

@@ -121,14 +121,54 @@ scope("MarkupRenderer", EntityKind.Parameter, () => {
     const parameterEntities = functionEntity.signatures[0].parameters;
     const ctx = createRenderContext();
 
+    const convertedParametersForSignature = convertParameterEntitiesForSignature(ctx, parameterEntities);
     const convertedParameterForDocumentation = convertParameterEntitiesForDocumentation(ctx, parameterEntities);
 
+    const renderedParametersForSignature = renderNode(ctx, convertedParametersForSignature);
     const renderedParameterForDocumentation = renderNode(ctx, convertedParameterForDocumentation);
 
+    it("should encapsulate default parameters in '[]' by default", () => {
+      expect(renderedParametersForSignature).toBe("[a]");
+    });
+
     it("should render default values", () => {
       expect(renderedParameterForDocumentation).toContain("Default: 7");
     });
 
+    it("should render an additional 'optional' tag by default", () => {
+      expect(renderedParameterForDocumentation).toContain("optional");
+    });
+
+  }
+
+  {
+
+    const testFileContent = ts`
+      export function test(a: number = 7) {}
+    `;
+
+    const { ctx: compilerContext, exportedSymbols } = compile(testFileContent);
+
+    const symbol = exportedSymbols.find(s => s.name === "test")!;
+    const functionEntity = createFunctionEntity(compilerContext, symbol);
+    const parameterEntities = functionEntity.signatures[0].parameters;
+    const ctx = createRenderContext();
+    ctx.config.renderConfig.html.renderDefaultValuesAsOptional = false;
+
+    const convertedParametersForSignature = convertParameterEntitiesForSignature(ctx, parameterEntities);
+    const convertedParameterForDocumentation = convertParameterEntitiesForDocumentation(ctx, parameterEntities);
+
+    const renderedParametersForSignature = renderNode(ctx, convertedParametersForSignature);
+    const renderedParameterForDocumentation = renderNode(ctx, convertedParameterForDocumentation);
+
+    it("should be possible to disable the encapsulation of default parameters in '[]'", () => {
+      expect(renderedParametersForSignature).toBe("a");
+    });
+
+    it("should be possible to disable the rendering of an additional `optional` tag for default values", () => {
+      expect(renderedParameterForDocumentation).not.toContain("optional");
+    });
+
   }
 
 });

src/renderer/markup/ast-converter/entities/parameter.ts

@@ -45,19 +45,34 @@ export function convertParameterEntitiesForSignature(ctx: MarkupRenderContexts,
     return undefined;
   }
 
-  const renderedParameters = parameterEntities.flatMap((parameter, index) => {
-    const convertedParameter = convertParameterEntityForSignature(ctx, parameter);
+  const renderConfig = getRenderConfig(ctx);
+
+  const renderedParameters = parameterEntities.flatMap((parameterEntity, index) => {
+    const convertedParameter = convertParameterEntityForSignature(ctx, parameterEntity);
+
     if(index === 0){
       return [
-        parameter.optional === true ? "[" : "",
+        parameterEntity.optional === true ||
+        renderConfig.renderDefaultValuesAsOptional && parameterEntity.initializer
+          ? "["
+          : "",
         ...convertedParameter,
-        parameter.optional === true ? "]" : ""
+        parameterEntity.optional === true ||
+        renderConfig.renderDefaultValuesAsOptional && parameterEntity.initializer
+          ? "]"
+          : ""
       ];
     } else {
       return [
-        parameter.optional === true ? "[, " : ", ",
+        parameterEntity.optional === true ||
+        renderConfig.renderDefaultValuesAsOptional && parameterEntity.initializer
+          ? "[, "
+          : ", ",
         ...convertedParameter,
-        parameter.optional === true ? "]" : ""
+        parameterEntity.optional === true ||
+        renderConfig.renderDefaultValuesAsOptional && parameterEntity.initializer
+          ? "]"
+          : ""
       ];
     }
   });
@@ -138,7 +153,8 @@ function convertParameterEntityForDocumentation(ctx: MarkupRenderContexts, param
 
   const description = parameterEntity.description && convertDescriptionForType(ctx, parameterEntity.description);
   const rest = parameterEntity.rest === true && encapsulate(translate("rest"), renderConfig.tagEncapsulation);
-  const optional = parameterEntity.optional === true && encapsulate(translate("optional"), renderConfig.tagEncapsulation);
+  const optional = (parameterEntity.optional === true || renderConfig.renderDefaultValuesAsOptional && parameterEntity.initializer) &&
+   encapsulate(translate("optional"), renderConfig.tagEncapsulation);
   const initializer = parameterEntity.initializer && convertInitializerForType(ctx, parameterEntity.initializer);
 
   const { inlineType, multilineType } = convertType(ctx, parameterEntity.type);
@@ -149,8 +165,8 @@ function convertParameterEntityForDocumentation(ctx: MarkupRenderContexts, param
         nameAnchor,
         inlineType,
         description,
-        optional,
         rest,
+        optional,
         initializer?.inlineInitializer
       )
     ),

src/renderer/markup/config/default.ts

@@ -16,6 +16,7 @@ const defaultRenderConfig: Complete<MarkupRenderConfig> = {
   parameterEncapsulation: ["`", "`"],
   propertyEncapsulation: ["`", "`"],
   renderClassMemberTitles: "tableOfContents",
+  renderDefaultValuesAsOptional: true,
   renderEntityPrefixes: "documentation",
   renderOrder: [
     EntityKind.Module,

src/renderer/markup/types-definitions/config.ts

@@ -21,6 +21,9 @@ export interface MarkupRenderConfig {
   /** Defines whether the renderer should render titles for object members. */
   renderClassMemberTitles?: boolean | "documentation" | "tableOfContents";
 
+  /** Defines whether the renderer should render an additional optional tag for default values. */
+  renderDefaultValuesAsOptional?: boolean;
+
   /** Defines whether the renderer should render prefixes for entities. */
   renderEntityPrefixes?: boolean | "documentation" | "tableOfContents";