From 4675f3d96af87cdc310db370435887c2f717719b Mon Sep 17 00:00:00 2001 From: Marco Link Date: Sat, 4 Feb 2023 11:09:14 +0100 Subject: [PATCH] feat: inotrduce field level comments (#208) --- README.md | 29 ++++++-------- src/renderer/type/js-doc-renderer.ts | 44 ++++++++++++++++++++-- test/renderer/type/js-doc-renderer.test.ts | 35 ++++++++++++++--- 3 files changed, 82 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index e5753b0..eef05e3 100644 --- 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,15 +340,9 @@ 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 @@ -361,12 +350,18 @@ const builder = new CFDefinitionsBuilder([ ```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 index 01af5e8..24f4564 100644 --- 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 | string; renderFieldsDocs?: (props: FieldsDocsOptionsProps) => OptionalKind | string; + renderFieldDocs?: (props: FieldDocsOptionsProps) => OptionalKind | string; }; export const defaultJsDocRenderOptions: Required = { @@ -68,7 +73,7 @@ export const defaultJsDocRenderOptions: Required = { 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 = { ], }; }, + + 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 index 85aa559..09934e1 100644 --- 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; }