Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: introduce field level comments #208

Merged
merged 1 commit into from
Feb 4, 2023
Merged

feat: introduce field level comments #208

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 12 additions & 17 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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).

Expand All @@ -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;
}

Expand Down
44 changes: 40 additions & 4 deletions src/renderer/type/js-doc-renderer.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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> = {
Expand Down Expand Up @@ -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',
Expand All @@ -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 */
Expand Down Expand Up @@ -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,
}),
);
}
}
}
};
}
35 changes: 30 additions & 5 deletions test/renderer/type/js-doc-renderer.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}

Expand Down Expand Up @@ -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;
}

Expand Down Expand Up @@ -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;
}

Expand Down Expand Up @@ -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;
}

Expand Down Expand Up @@ -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;
}

Expand Down