feat: inotrduce field level comments (#208)

contentful-userland · Feb 4, 2023 · 4675f3d · 4675f3d
1 parent 9e6ca21
commit 4675f3d
Show file tree

Hide file tree

Showing 3 changed files with 82 additions and 26 deletions.
diff --git a/README.md b/README.md
@@ -271,14 +271,9 @@ If no custom renderers given, `CFDefinitionsBuilder` creates a `DefaultContentTy
 #### Example Usage
 
 ```typescript
-import { 
-  CFDefinitionsBuilder, 
-  DefaultContentTypeRenderer 
-} from 'cf-content-types-generator';
+import { CFDefinitionsBuilder, DefaultContentTypeRenderer } from 'cf-content-types-generator';
 
-const builder = new CFDefinitionsBuilder([
-  new DefaultContentTypeRenderer()
-]);
+const builder = new CFDefinitionsBuilder([new DefaultContentTypeRenderer()]);
 ```
 
 ## LocalizedContentTypeRenderer
@@ -336,7 +331,7 @@ const localizedCategory: LocalizedTypeCategory<'DE-de' | 'En-en'> = {
 };
 ```
 
-## JSDocContentTypeRenderer
+## JSDocRenderer
 
 Adds [JSDoc](https://jsdoc.app/) Comments to every Entry type and Field type (created by the default renderer, or a renderer that creates the same entry and field type names). This renderer can be customized through [renderer options](src/renderer/type/js-doc-renderer.ts#L20).
 
@@ -345,28 +340,28 @@ JSDocContentTypeRenderer can only render comments for already rendered types. It
 #### Example Usage
 
 ```typescript
-import { 
-  CFDefinitionsBuilder, 
-  JsDocRenderer 
-} from 'cf-content-types-generator';
+import { CFDefinitionsBuilder, JsDocRenderer } from 'cf-content-types-generator';
 
-const builder = new CFDefinitionsBuilder([
-  new DefaultContentTypeRenderer(), 
-  new JsDocRenderer()
-]);
+const builder = new CFDefinitionsBuilder([new DefaultContentTypeRenderer(), new JsDocRenderer()]);
 ```
 
 #### Example output
 
 ```typescript
 import * as Contentful from 'contentful';
 /**
- * Fields type definition for content type 'TypeAnimalFields'
+ * Fields type definition for content type 'TypeAnimal'
  * @name TypeAnimalFields
  * @type {TypeAnimalFields}
  * @memberof TypeAnimal
  */
 export interface TypeAnimalFields {
+
+  /**
+   * Field type definition for field 'bread' (Bread)
+   * @name Bread
+   * @localized false
+  */
   bread: Contentful.EntryFields.Symbol;
 }
 

diff --git a/src/renderer/type/js-doc-renderer.ts b/src/renderer/type/js-doc-renderer.ts
@@ -6,20 +6,25 @@ import { BaseContentTypeRenderer } from './base-content-type-renderer';
 
 type EntryDocsOptionsProps = {
   /* Name of generated Entry type */
-  name: string;
+  readonly name: string;
   readonly contentType: CFContentType;
 };
 
 type FieldsDocsOptionsProps = {
   /* Name of generated Fields type */
-  name: string;
-  entryName: string;
+  readonly name: string;
+  readonly entryName: string;
   readonly fields: Field[];
 };
 
+type FieldDocsOptionsProps = {
+  readonly field: Field;
+};
+
 export type JSDocRenderOptions = {
   renderEntryDocs?: (props: EntryDocsOptionsProps) => OptionalKind<JSDocStructure> | string;
   renderFieldsDocs?: (props: FieldsDocsOptionsProps) => OptionalKind<JSDocStructure> | string;
+  renderFieldDocs?: (props: FieldDocsOptionsProps) => OptionalKind<JSDocStructure> | string;
 };
 
 export const defaultJsDocRenderOptions: Required<JSDocRenderOptions> = {
@@ -68,7 +73,7 @@ export const defaultJsDocRenderOptions: Required<JSDocRenderOptions> = {
 
   renderFieldsDocs: ({ name, entryName }) => {
     return {
-      description: `Fields type definition for content type '${name}'`,
+      description: `Fields type definition for content type '${entryName}'`,
       tags: [
         {
           tagName: 'name',
@@ -85,6 +90,22 @@ export const defaultJsDocRenderOptions: Required<JSDocRenderOptions> = {
       ],
     };
   },
+
+  renderFieldDocs: ({ field }) => {
+    return {
+      description: `Field type definition for field '${field.id}' (${field.name})`,
+      tags: [
+        {
+          tagName: 'name',
+          text: field.name,
+        },
+        {
+          tagName: 'localized',
+          text: field.localized.toString(),
+        },
+      ],
+    };
+  },
 };
 
 /* JsDocRenderer only works in conjunction with other Renderers. It relays on previously rendered Interfaces */
@@ -125,6 +146,21 @@ export class JsDocRenderer extends BaseContentTypeRenderer {
           fields: contentType.fields,
         }),
       );
+
+      const fields = fieldsInterface.getProperties();
+
+      for (const field of fields) {
+        const fieldName = field.getName();
+        const contentTypeField = contentType.fields.find((f) => f.id === fieldName);
+
+        if (contentTypeField) {
+          field.addJsDoc(
+            this.renderOptions.renderFieldDocs({
+              field: contentTypeField,
+            }),
+          );
+        }
+      }
     }
   };
 }
diff --git a/test/renderer/type/js-doc-renderer.test.ts b/test/renderer/type/js-doc-renderer.test.ts
@@ -57,12 +57,17 @@ describe('A JSDoc content type renderer class', () => {
         import * as Contentful from "contentful";
         
         /**
-         * Fields type definition for content type 'TypeAnimalFields'
+         * Fields type definition for content type 'TypeAnimal'
          * @name TypeAnimalFields
          * @type {TypeAnimalFields}
          * @memberof TypeAnimal
          */
         export interface TypeAnimalFields {
+            /**
+             * Field type definition for field 'bread' (Bread)
+             * @name Bread
+             * @localized false
+             */
             bread: Contentful.EntryFields.Symbol;
         }
         
@@ -97,12 +102,17 @@ describe('A JSDoc content type renderer class', () => {
         import * as Contentful from "contentful";
         
         /**
-         * Fields type definition for content type 'TypeAnimalFields'
+         * Fields type definition for content type 'TypeAnimal'
          * @name TypeAnimalFields
          * @type {TypeAnimalFields}
          * @memberof TypeAnimal
          */
         export interface TypeAnimalFields {
+            /**
+             * Field type definition for field 'bread' (Bread)
+             * @name Bread
+             * @localized false
+             */
             bread: Contentful.EntryFields.Symbol;
         }
         
@@ -134,12 +144,17 @@ describe('A JSDoc content type renderer class', () => {
         import * as Contentful from "contentful";
         
         /**
-         * Fields type definition for content type 'TypeAnimalFields'
+         * Fields type definition for content type 'TypeAnimal'
          * @name TypeAnimalFields
          * @type {TypeAnimalFields}
          * @memberof TypeAnimal
          */
         export interface TypeAnimalFields {
+            /**
+             * Field type definition for field 'bread' (Bread)
+             * @name Bread
+             * @localized false
+             */
             bread: Contentful.EntryFields.Symbol;
         }
         
@@ -171,12 +186,17 @@ describe('A JSDoc content type renderer class', () => {
         import * as Contentful from "contentful";
         
         /**
-         * Fields type definition for content type 'TypeAnimalFields'
+         * Fields type definition for content type 'TypeAnimal'
          * @name TypeAnimalFields
          * @type {TypeAnimalFields}
          * @memberof TypeAnimal
          */
         export interface TypeAnimalFields {
+            /**
+             * Field type definition for field 'bread' (Bread)
+             * @name Bread
+             * @localized false
+             */
             bread: Contentful.EntryFields.Symbol;
         }
         
@@ -216,12 +236,17 @@ describe('A JSDoc content type renderer class', () => {
         import * as Contentful from "contentful";
         
         /**
-         * Fields type definition for content type 'TypeAnimalFields'
+         * Fields type definition for content type 'TypeAnimal'
          * @name TypeAnimalFields
          * @type {TypeAnimalFields}
          * @memberof TypeAnimal
          */
         export interface TypeAnimalFields {
+            /**
+             * Field type definition for field 'bread' (Bread)
+             * @name Bread
+             * @localized false
+             */
             bread: Contentful.EntryFields.Symbol;
         }