From 618e3b98357e1e549102e620b70bbc04eb2e0ec3 Mon Sep 17 00:00:00 2001 From: Patrick Wolfert Date: Mon, 20 May 2024 10:00:00 -0700 Subject: [PATCH 1/4] Added sorting capabilities and tests I'm going to actually leave the enums out of it because they get converted into numbers by default, and sorting them becomes meaningless. In the next commit, I'll change the name of everything to reflect that --- src/__tests__/data/SimpleEnumsAndUnions.tsx | 18 +++++++ src/__tests__/parser.ts | 57 +++++++++++++++++++++ src/parser.ts | 11 ++++ 3 files changed, 86 insertions(+) create mode 100644 src/__tests__/data/SimpleEnumsAndUnions.tsx diff --git a/src/__tests__/data/SimpleEnumsAndUnions.tsx b/src/__tests__/data/SimpleEnumsAndUnions.tsx new file mode 100644 index 0000000..ca604e9 --- /dev/null +++ b/src/__tests__/data/SimpleEnumsAndUnions.tsx @@ -0,0 +1,18 @@ +type SampleUnion = 'h1' | 'h6' | 'h2' | 'h4' | 'h5' | 'h3'; +enum SampleEnum { + Z = 'Z', + C = 'C', + B = 'B', + A = 'A', + X = 'X', + Y = 'Y' +} + +interface Props { + /** sampleUnionProp description */ + sampleUnionProp: SampleUnion; + /** sampleEnumProp description */ + sampleEnumProp: SampleEnum; +} + +export const SimpleEnumsAndUnions = (props: Props) =>
; diff --git a/src/__tests__/parser.ts b/src/__tests__/parser.ts index c185147..0c933f9 100644 --- a/src/__tests__/parser.ts +++ b/src/__tests__/parser.ts @@ -1448,6 +1448,63 @@ describe('parser', () => { }); }); + describe('Sorting enums', () => { + it('does not sort enums by default', () => { + check( + 'SimpleEnumsAndUnions', + { + SimpleEnumsAndUnions: { + sampleUnionProp: { + raw: 'SampleUnion', + type: 'enum', + value: [ + { value: '"h1"' }, + { value: '"h6"' }, + { value: '"h2"' }, + { value: '"h4"' }, + { value: '"h5"' }, + { value: '"h3"' } + ] + } + } + }, + false, + null, + { + shouldExtractLiteralValuesFromEnum: true + } + ); + }); + + it('sorts enums when shouldSortEnums is true', () => { + check( + 'SimpleEnumsAndUnions', + { + SimpleEnumsAndUnions: { + sampleUnionProp: { + raw: 'SampleUnion', + type: 'enum', + value: [ + { value: '"h1"' }, + { value: '"h2"' }, + { value: '"h3"' }, + { value: '"h4"' }, + { value: '"h5"' }, + { value: '"h6"' } + ] + } + } + }, + false, + null, + { + shouldExtractLiteralValuesFromEnum: true, + shouldSortEnums: true + } + ); + }); + }); + describe('Returning not string default props ', () => { it('returns not string defaultProps', () => { check( diff --git a/src/parser.ts b/src/parser.ts index ccf9b2f..800507a 100644 --- a/src/parser.ts +++ b/src/parser.ts @@ -87,6 +87,7 @@ export interface ParserOptions { shouldExtractLiteralValuesFromEnum?: boolean; shouldRemoveUndefinedFromOptional?: boolean; shouldExtractValuesFromUnion?: boolean; + shouldSortEnums?: boolean; skipChildrenPropWithoutDoc?: boolean; savePropValueAsString?: boolean; shouldIncludePropTagMap?: boolean; @@ -220,6 +221,7 @@ export class Parser { private readonly shouldRemoveUndefinedFromOptional: boolean; private readonly shouldExtractLiteralValuesFromEnum: boolean; private readonly shouldExtractValuesFromUnion: boolean; + private readonly shouldSortEnums: boolean; private readonly savePropValueAsString: boolean; private readonly shouldIncludePropTagMap: boolean; private readonly shouldIncludeExpression: boolean; @@ -230,6 +232,7 @@ export class Parser { shouldExtractLiteralValuesFromEnum, shouldRemoveUndefinedFromOptional, shouldExtractValuesFromUnion, + shouldSortEnums, shouldIncludePropTagMap, shouldIncludeExpression } = opts; @@ -242,6 +245,7 @@ export class Parser { shouldRemoveUndefinedFromOptional ); this.shouldExtractValuesFromUnion = Boolean(shouldExtractValuesFromUnion); + this.shouldSortEnums = Boolean(shouldSortEnums); this.savePropValueAsString = Boolean(savePropValueAsString); this.shouldIncludePropTagMap = Boolean(shouldIncludePropTagMap); this.shouldIncludeExpression = Boolean(shouldIncludeExpression); @@ -598,6 +602,7 @@ export class Parser { if (type.getSymbol()) { commentInfo = { ...this.getFullJsDocComment(type.getSymbol()!) }; } + // console.log(this.getValuesFromUnionType(type)) return { value: this.getValuesFromUnionType(type), ...commentInfo @@ -635,6 +640,12 @@ export class Parser { value = value.filter(option => option.value != 'undefined'); } + if (this.shouldSortEnums) { + value.sort((a, b) => + a.value.toString().localeCompare(b.value.toString()) + ); + } + return { name: 'enum', raw: propTypeString, From 2865964654db1915e9e5650b462544b8aa7273bc Mon Sep 17 00:00:00 2001 From: Patrick Wolfert Date: Mon, 20 May 2024 10:07:07 -0700 Subject: [PATCH 2/4] Change naming to reflect that we're only targeting unions now. And add docs --- README.md | 4 ++++ src/__tests__/data/SimpleEnumsAndUnions.tsx | 18 ------------------ src/__tests__/data/SimpleUnions.tsx | 8 ++++++++ src/__tests__/parser.ts | 16 ++++++++-------- src/parser.ts | 10 +++++----- 5 files changed, 25 insertions(+), 31 deletions(-) delete mode 100644 src/__tests__/data/SimpleEnumsAndUnions.tsx create mode 100644 src/__tests__/data/SimpleUnions.tsx diff --git a/README.md b/README.md index a8830e2..c9486a1 100644 --- a/README.md +++ b/README.md @@ -140,6 +140,10 @@ If set to true, string enums and unions will be converted to docgen enum format. If set to true, every unions will be converted to docgen enum format. +### `shouldSortUnions`: boolean + +When used in combination with `shouldExtractValuesFromUnion`, sorts union members in string-sort order when set to true. This is useful for ensuring the same order of members every time. + ### `skipChildrenPropWithoutDoc`: boolean (default: `true`) If set to false the docs for the `children` prop will be generated even without an explicit description. diff --git a/src/__tests__/data/SimpleEnumsAndUnions.tsx b/src/__tests__/data/SimpleEnumsAndUnions.tsx deleted file mode 100644 index ca604e9..0000000 --- a/src/__tests__/data/SimpleEnumsAndUnions.tsx +++ /dev/null @@ -1,18 +0,0 @@ -type SampleUnion = 'h1' | 'h6' | 'h2' | 'h4' | 'h5' | 'h3'; -enum SampleEnum { - Z = 'Z', - C = 'C', - B = 'B', - A = 'A', - X = 'X', - Y = 'Y' -} - -interface Props { - /** sampleUnionProp description */ - sampleUnionProp: SampleUnion; - /** sampleEnumProp description */ - sampleEnumProp: SampleEnum; -} - -export const SimpleEnumsAndUnions = (props: Props) =>
; diff --git a/src/__tests__/data/SimpleUnions.tsx b/src/__tests__/data/SimpleUnions.tsx new file mode 100644 index 0000000..1719497 --- /dev/null +++ b/src/__tests__/data/SimpleUnions.tsx @@ -0,0 +1,8 @@ +type SampleUnion = 'h1' | 'h6' | 'h2' | 'h4' | 'h5' | 'h3'; + +interface Props { + /** sampleUnionProp description */ + sampleUnionProp: SampleUnion; +} + +export const SimpleUnions = (props: Props) =>
; diff --git a/src/__tests__/parser.ts b/src/__tests__/parser.ts index 0c933f9..16f9cfb 100644 --- a/src/__tests__/parser.ts +++ b/src/__tests__/parser.ts @@ -1448,12 +1448,12 @@ describe('parser', () => { }); }); - describe('Sorting enums', () => { - it('does not sort enums by default', () => { + describe('Sorting unions', () => { + it('does not sort union members by default', () => { check( - 'SimpleEnumsAndUnions', + 'SimpleUnions', { - SimpleEnumsAndUnions: { + SimpleUnions: { sampleUnionProp: { raw: 'SampleUnion', type: 'enum', @@ -1476,11 +1476,11 @@ describe('parser', () => { ); }); - it('sorts enums when shouldSortEnums is true', () => { + it('sorts union members when shouldSortUnions is true', () => { check( - 'SimpleEnumsAndUnions', + 'SimpleUnions', { - SimpleEnumsAndUnions: { + SimpleUnions: { sampleUnionProp: { raw: 'SampleUnion', type: 'enum', @@ -1499,7 +1499,7 @@ describe('parser', () => { null, { shouldExtractLiteralValuesFromEnum: true, - shouldSortEnums: true + shouldSortUnions: true } ); }); diff --git a/src/parser.ts b/src/parser.ts index 800507a..c20a567 100644 --- a/src/parser.ts +++ b/src/parser.ts @@ -87,7 +87,7 @@ export interface ParserOptions { shouldExtractLiteralValuesFromEnum?: boolean; shouldRemoveUndefinedFromOptional?: boolean; shouldExtractValuesFromUnion?: boolean; - shouldSortEnums?: boolean; + shouldSortUnions?: boolean; skipChildrenPropWithoutDoc?: boolean; savePropValueAsString?: boolean; shouldIncludePropTagMap?: boolean; @@ -221,7 +221,7 @@ export class Parser { private readonly shouldRemoveUndefinedFromOptional: boolean; private readonly shouldExtractLiteralValuesFromEnum: boolean; private readonly shouldExtractValuesFromUnion: boolean; - private readonly shouldSortEnums: boolean; + private readonly shouldSortUnions: boolean; private readonly savePropValueAsString: boolean; private readonly shouldIncludePropTagMap: boolean; private readonly shouldIncludeExpression: boolean; @@ -232,7 +232,7 @@ export class Parser { shouldExtractLiteralValuesFromEnum, shouldRemoveUndefinedFromOptional, shouldExtractValuesFromUnion, - shouldSortEnums, + shouldSortUnions, shouldIncludePropTagMap, shouldIncludeExpression } = opts; @@ -245,7 +245,7 @@ export class Parser { shouldRemoveUndefinedFromOptional ); this.shouldExtractValuesFromUnion = Boolean(shouldExtractValuesFromUnion); - this.shouldSortEnums = Boolean(shouldSortEnums); + this.shouldSortUnions = Boolean(shouldSortUnions); this.savePropValueAsString = Boolean(savePropValueAsString); this.shouldIncludePropTagMap = Boolean(shouldIncludePropTagMap); this.shouldIncludeExpression = Boolean(shouldIncludeExpression); @@ -640,7 +640,7 @@ export class Parser { value = value.filter(option => option.value != 'undefined'); } - if (this.shouldSortEnums) { + if (this.shouldSortUnions) { value.sort((a, b) => a.value.toString().localeCompare(b.value.toString()) ); From 0c6b98cff6df276c365be27ba12a1db188cbd2d7 Mon Sep 17 00:00:00 2001 From: Patrick Wolfert Date: Mon, 20 May 2024 10:46:23 -0700 Subject: [PATCH 3/4] Get rid of debug logging --- src/parser.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/src/parser.ts b/src/parser.ts index c20a567..d21f31f 100644 --- a/src/parser.ts +++ b/src/parser.ts @@ -602,7 +602,6 @@ export class Parser { if (type.getSymbol()) { commentInfo = { ...this.getFullJsDocComment(type.getSymbol()!) }; } - // console.log(this.getValuesFromUnionType(type)) return { value: this.getValuesFromUnionType(type), ...commentInfo From c81d62ede8533fe045bba40b7b8cb9e2097e9071 Mon Sep 17 00:00:00 2001 From: Patrick Wolfert Date: Mon, 20 May 2024 11:25:18 -0700 Subject: [PATCH 4/4] Correction: Can also work with `shouldExtractLiteralValuesFromEnum` --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c9486a1..dd5bdf0 100644 --- a/README.md +++ b/README.md @@ -142,7 +142,7 @@ If set to true, every unions will be converted to docgen enum format. ### `shouldSortUnions`: boolean -When used in combination with `shouldExtractValuesFromUnion`, sorts union members in string-sort order when set to true. This is useful for ensuring the same order of members every time. +When used in combination with `shouldExtractValuesFromUnion` or `shouldExtractLiteralValuesFromEnum`, sorts union members in string-sort order when set to true. This is useful for ensuring the same order of members every time. ### `skipChildrenPropWithoutDoc`: boolean (default: `true`)