From e1c7a53f7af05a8f1b414b34af6cd06ad9f189c5 Mon Sep 17 00:00:00 2001 From: man Date: Sat, 8 May 2021 23:25:11 +0200 Subject: [PATCH 1/7] Implement vertical align of param --- README.md | 9 +++++---- package-lock.json | 2 +- package.json | 10 ++++++++++ src/doc.ts | 29 ++++++++++++++++++++++++++++- 4 files changed, 44 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 4cc6ba8..5160998 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,8 @@ This extension contributes the following settings: * `php-docblocker.returnVoid`: set to `false` to turn off the automatic void return type when it can't be determined * `php-docblocker.extra`: an array of extra tags to add to each DocBlock (These can include tabstops and snippet variables) * `php-docblocker.useShortNames`: Whether we should use short type names. e.g. bool or boolean -* `php-docblocker.qualifyClassNames`: When adding type hints for class names search namespace use statements and qualify the class +* `php-docblocker.qualifyClassNames`: When adding type hints for class names search namespace use statements and qualify the class +* `php-docblocker.alignParams`: set to `true` to align params vertically and add appropriate spaces after param names * `php-docblocker.author`: An object containing your default author tag settings * `php-docblocker.functionTemplate`: See below for how to set up docblock templates * `php-docblocker.propertyTemplate`: See below for how to set up docblock templates @@ -74,7 +75,7 @@ config option per key to add additional control. #### Configured function template example -In the example below we have added some gap configuration and removed the return tag for our template as well as +In the example below we have added some gap configuration and removed the return tag for our template as well as changing the default order. This means we'll never have a @return tag and extra comes before the params. It's also worth pointing out that the gapAfter in the message is the same as setting the gap config option in the main config to true. @@ -93,8 +94,8 @@ to true. #### Configured function with extra content and placeholders -The example below won't have a return tag and will add in an author tag with correct placeholders depending on -how many options you have. You can put in placeholders by using `###` in place of the tab stop number and it +The example below won't have a return tag and will add in an author tag with correct placeholders depending on +how many options you have. You can put in placeholders by using `###` in place of the tab stop number and it will be calculated at generation time. ```json diff --git a/package-lock.json b/package-lock.json index 81ff3ef..6e08e79 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "php-docblocker", - "version": "2.0.1", + "version": "2.1.0", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/package.json b/package.json index 1a0ba3b..dab9356 100644 --- a/package.json +++ b/package.json @@ -71,6 +71,16 @@ "default": false, "description": "Fully qualifies any data types used in param and returns by reading the namespaces." }, + "php-docblocker.alignParams": { + "type": "boolean", + "default": true, + "description": "Vertically aligns param types and names with additional spaces." + }, + "php-docblocker.alignReturn": { + "type": "boolean", + "default": true, + "description": "Vertically aligns return with above param statements." + }, "php-docblocker.functionTemplate": { "type": "object", "default": null, diff --git a/src/doc.ts b/src/doc.ts index 3f90087..8be6c07 100644 --- a/src/doc.ts +++ b/src/doc.ts @@ -89,6 +89,7 @@ export class Doc let extra = Config.instance.get('extra'); let gap = Config.instance.get('gap'); let returnGap = Config.instance.get('returnGap'); + let alignParams = Config.instance.get('alignParams'); let returnString = ""; let varString = ""; @@ -105,11 +106,37 @@ export class Doc if (this.params.length) { paramString = ""; + + // Loop through params and find max length of type and name. + let maxParamTypeLength = 0; + let maxParamNameLength = 0; + this.params.forEach(param => { + let paramType = param.type; + if (paramType.length > maxParamTypeLength) { + maxParamTypeLength = paramType.length; + } + let paramName = param.name.replace('$', '\\$') + if (paramName.length > maxParamNameLength) { + maxParamNameLength = paramName.length; + } + }); + this.params.forEach(param => { if (paramString != "") { paramString += "\n"; } - paramString += "@param \${###:"+param.type+"} " + param.name.replace('$', '\\$'); + + let paramType = param.type; + let paramName = param.name.replace('$', '\\$'); + + if (alignParams) { + // Append additional spaces on param type and param name. + paramType = paramType + (Array(maxParamTypeLength - paramType.length).fill(' ').join('')); + // Add 1 to array size, so there is already a space appended for typing comments. + paramName = paramName + (Array(1 + maxParamNameLength - paramName.length).fill(' ').join('')); + } + + paramString += "@param \${###:"+paramType+"} " + paramName; }); } From fba055a58d59457ddf3c22fce899ea1d6efdb2eb Mon Sep 17 00:00:00 2001 From: man Date: Sat, 8 May 2021 23:50:08 +0200 Subject: [PATCH 2/7] Set param default false, align return statement --- package.json | 4 ++-- src/doc.ts | 39 ++++++++++++++++++++++++++++++--------- 2 files changed, 32 insertions(+), 11 deletions(-) diff --git a/package.json b/package.json index dab9356..c4a4193 100644 --- a/package.json +++ b/package.json @@ -73,12 +73,12 @@ }, "php-docblocker.alignParams": { "type": "boolean", - "default": true, + "default": false, "description": "Vertically aligns param types and names with additional spaces." }, "php-docblocker.alignReturn": { "type": "boolean", - "default": true, + "default": false, "description": "Vertically aligns return with above param statements." }, "php-docblocker.functionTemplate": { diff --git a/src/doc.ts b/src/doc.ts index 8be6c07..bf5f1e0 100644 --- a/src/doc.ts +++ b/src/doc.ts @@ -90,6 +90,8 @@ export class Doc let gap = Config.instance.get('gap'); let returnGap = Config.instance.get('returnGap'); let alignParams = Config.instance.get('alignParams'); + // Align return is false if align params is not active. + let alignReturn = alignParams ? Config.instance.get('alignReturn') : false; let returnString = ""; let varString = ""; @@ -104,12 +106,10 @@ export class Doc messageString = "\${###" + (this.message != "" ? ':' : '') + this.message + "}"; + // Loop through params and find max length of type and name. + let maxParamTypeLength = 0; + let maxParamNameLength = 0; if (this.params.length) { - paramString = ""; - - // Loop through params and find max length of type and name. - let maxParamTypeLength = 0; - let maxParamNameLength = 0; this.params.forEach(param => { let paramType = param.type; if (paramType.length > maxParamTypeLength) { @@ -120,6 +120,16 @@ export class Doc maxParamNameLength = paramName.length; } }); + } + if (this.return && (this.return != 'void' || Config.instance.get('returnVoid')) && alignReturn) { + let returnType = this.return; + if (returnType.length > maxParamTypeLength) { + maxParamTypeLength = returnType.length; + } + } + + if (this.params.length) { + paramString = ""; this.params.forEach(param => { if (paramString != "") { @@ -129,14 +139,21 @@ export class Doc let paramType = param.type; let paramName = param.name.replace('$', '\\$'); + // Prepend space to align '@param' and '@return'. + let prependSpace = ''; + if (alignReturn) { + prependSpace = ' '; + } + + let appendSpace = ''; if (alignParams) { // Append additional spaces on param type and param name. - paramType = paramType + (Array(maxParamTypeLength - paramType.length).fill(' ').join('')); + appendSpace = Array(maxParamTypeLength - paramType.length).fill(' ').join(''); // Add 1 to array size, so there is already a space appended for typing comments. - paramName = paramName + (Array(1 + maxParamNameLength - paramName.length).fill(' ').join('')); + paramName += (Array(1 + maxParamNameLength - paramName.length).fill(' ').join('')); } - paramString += "@param \${###:"+paramType+"} " + paramName; + paramString += "@param "+prependSpace+"\${###:"+paramType+"} " + appendSpace + paramName; }); } @@ -145,7 +162,11 @@ export class Doc } if (this.return && (this.return != 'void' || Config.instance.get('returnVoid'))) { - returnString = "@return \${###:" +this.return + "}"; + let appendSpace = ''; + if (alignReturn) { + appendSpace = (Array(1 + maxParamNameLength).fill(' ').join('')); + } + returnString = "@return \${###:" +this.return + "}" + appendSpace; } if (Array.isArray(extra) && extra.length > 0) { From 055541772cd431965e3141fe3f7c0fd82c474855 Mon Sep 17 00:00:00 2001 From: man Date: Sun, 9 May 2021 11:27:06 +0200 Subject: [PATCH 3/7] Add README comment and cleanup code --- README.md | 1 + src/doc.ts | 20 ++++++++++---------- 2 files changed, 11 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 5160998..7e3d6e5 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,7 @@ This extension contributes the following settings: * `php-docblocker.useShortNames`: Whether we should use short type names. e.g. bool or boolean * `php-docblocker.qualifyClassNames`: When adding type hints for class names search namespace use statements and qualify the class * `php-docblocker.alignParams`: set to `true` to align params vertically and add appropriate spaces after param names +* `php-docblocker.alignReturn`: set to `true` to align return vertically with above params statements, this setting requires align params to also be active * `php-docblocker.author`: An object containing your default author tag settings * `php-docblocker.functionTemplate`: See below for how to set up docblock templates * `php-docblocker.propertyTemplate`: See below for how to set up docblock templates diff --git a/src/doc.ts b/src/doc.ts index bf5f1e0..540f604 100644 --- a/src/doc.ts +++ b/src/doc.ts @@ -121,6 +121,7 @@ export class Doc } }); } + // If align return is active, check if it has a longer type. if (this.return && (this.return != 'void' || Config.instance.get('returnVoid')) && alignReturn) { let returnType = this.return; if (returnType.length > maxParamTypeLength) { @@ -130,7 +131,6 @@ export class Doc if (this.params.length) { paramString = ""; - this.params.forEach(param => { if (paramString != "") { paramString += "\n"; @@ -139,21 +139,21 @@ export class Doc let paramType = param.type; let paramName = param.name.replace('$', '\\$'); - // Prepend space to align '@param' and '@return'. let prependSpace = ''; - if (alignReturn) { - prependSpace = ' '; - } - let appendSpace = ''; if (alignParams) { // Append additional spaces on param type and param name. - appendSpace = Array(maxParamTypeLength - paramType.length).fill(' ').join(''); + prependSpace = Array(maxParamTypeLength - paramType.length).fill(' ').join(''); // Add 1 to array size, so there is already a space appended for typing comments. - paramName += (Array(1 + maxParamNameLength - paramName.length).fill(' ').join('')); + appendSpace = Array(1 + maxParamNameLength - paramName.length).fill(' ').join(''); } - paramString += "@param "+prependSpace+"\${###:"+paramType+"} " + appendSpace + paramName; + paramString += + "@param " + + // Add extra space to align '@param' and '@return'. + (alignReturn ? ' ' : '') + + "\${###:"+paramType+"} " + + prependSpace + paramName + appendSpace; }); } @@ -164,7 +164,7 @@ export class Doc if (this.return && (this.return != 'void' || Config.instance.get('returnVoid'))) { let appendSpace = ''; if (alignReturn) { - appendSpace = (Array(1 + maxParamNameLength).fill(' ').join('')); + appendSpace = Array(1 + maxParamNameLength).fill(' ').join(''); } returnString = "@return \${###:" +this.return + "}" + appendSpace; } From 3d8ef37d580ca1e70f578db4acb4027fbaac01ef Mon Sep 17 00:00:00 2001 From: man Date: Sun, 9 May 2021 12:11:59 +0200 Subject: [PATCH 4/7] Only calculated max param length when param is true and WIP feature tests --- src/doc.ts | 2 +- test/fixtures/doc.json | 50 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 51 insertions(+), 1 deletion(-) diff --git a/src/doc.ts b/src/doc.ts index 540f604..62dba17 100644 --- a/src/doc.ts +++ b/src/doc.ts @@ -109,7 +109,7 @@ export class Doc // Loop through params and find max length of type and name. let maxParamTypeLength = 0; let maxParamNameLength = 0; - if (this.params.length) { + if (this.params.length && alignParams) { this.params.forEach(param => { let paramType = param.type; if (paramType.length > maxParamTypeLength) { diff --git a/test/fixtures/doc.json b/test/fixtures/doc.json index a7b45e5..5768150 100644 --- a/test/fixtures/doc.json +++ b/test/fixtures/doc.json @@ -325,5 +325,55 @@ " * @param ${4:int} \\$name", " */" ] + }, + { + "name": "Align params", + "config": { + "gap": true, + "alignParams": true + }, + "input": { + "message": "Undocumented function", + "params": [ + { + "name": "$name", + "type": "int" + } + ], + "return": "void" + }, + "expected": [ + "/**", + " * ${1:Undocumented function}", + " *", + " * @param ${2:int} \\$name", + " * @return ${3:void}", + " */" + ] + }, + { + "name": "Align params and return statement", + "config": { + "gap": true, + "alignParams": true + }, + "input": { + "message": "Undocumented function", + "params": [ + { + "name": "$name", + "type": "int" + } + ], + "return": "void" + }, + "expected": [ + "/**", + " * ${1:Undocumented function}", + " *", + " * @param ${2:int} \\$name ", + " * @return ${3:void} ", + " */" + ] } ] From d9a45bad634bb9638e5d801c4a894a0184528065 Mon Sep 17 00:00:00 2001 From: man Date: Sun, 9 May 2021 12:22:38 +0200 Subject: [PATCH 5/7] Fix feature tests --- test/fixtures/doc.json | 55 ++++++++++++++++++++++++++++++++++++------ 1 file changed, 48 insertions(+), 7 deletions(-) diff --git a/test/fixtures/doc.json b/test/fixtures/doc.json index 5768150..51b2683 100644 --- a/test/fixtures/doc.json +++ b/test/fixtures/doc.json @@ -335,9 +335,44 @@ "input": { "message": "Undocumented function", "params": [ + { + "name": "$nameLong", + "type": "int" + }, { "name": "$name", + "type": "string" + } + ], + "return": "LongClassName" + }, + "expected": [ + "/**", + " * ${1:Undocumented function}", + " *", + " * @param ${2:int} \\$nameLong ", + " * @param ${2:string} \\$name ", + " * @return ${3:LongClassName}", + " */" + ] + }, + { + "name": "Align params without return statement", + "config": { + "gap": true, + "alignParams": true, + "returnVoid": false + }, + "input": { + "message": "Undocumented function", + "params": [ + { + "name": "$nameLong", "type": "int" + }, + { + "name": "$name", + "type": "string" } ], "return": "void" @@ -346,8 +381,8 @@ "/**", " * ${1:Undocumented function}", " *", - " * @param ${2:int} \\$name", - " * @return ${3:void}", + " * @param ${2:int} \\$nameLong ", + " * @param ${2:string} \\$name ", " */" ] }, @@ -355,24 +390,30 @@ "name": "Align params and return statement", "config": { "gap": true, - "alignParams": true + "alignParams": true, + "alignReturn": true }, "input": { "message": "Undocumented function", "params": [ { - "name": "$name", + "name": "$nameLong", "type": "int" + }, + { + "name": "$name", + "type": "string" } ], - "return": "void" + "return": "LongClassName" }, "expected": [ "/**", " * ${1:Undocumented function}", " *", - " * @param ${2:int} \\$name ", - " * @return ${3:void} ", + " * @param ${2:int} \\$nameLong ", + " * @param ${2:string} \\$name ", + " * @return ${3:LongClassName} ", " */" ] } From 38aaec7b98e933c55d975bd5a54120b634cbe8d8 Mon Sep 17 00:00:00 2001 From: man Date: Sun, 9 May 2021 12:39:18 +0200 Subject: [PATCH 6/7] Fix param numbering --- test/fixtures/doc.json | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/test/fixtures/doc.json b/test/fixtures/doc.json index 51b2683..a91a836 100644 --- a/test/fixtures/doc.json +++ b/test/fixtures/doc.json @@ -351,8 +351,8 @@ " * ${1:Undocumented function}", " *", " * @param ${2:int} \\$nameLong ", - " * @param ${2:string} \\$name ", - " * @return ${3:LongClassName}", + " * @param ${3:string} \\$name ", + " * @return ${4:LongClassName}", " */" ] }, @@ -382,7 +382,7 @@ " * ${1:Undocumented function}", " *", " * @param ${2:int} \\$nameLong ", - " * @param ${2:string} \\$name ", + " * @param ${3:string} \\$name ", " */" ] }, @@ -412,8 +412,8 @@ " * ${1:Undocumented function}", " *", " * @param ${2:int} \\$nameLong ", - " * @param ${2:string} \\$name ", - " * @return ${3:LongClassName} ", + " * @param ${3:string} \\$name ", + " * @return ${4:LongClassName} ", " */" ] } From 03b21348593fd3edfabc4bec4b7039e1f0f93387 Mon Sep 17 00:00:00 2001 From: man Date: Sun, 9 May 2021 12:46:57 +0200 Subject: [PATCH 7/7] Implement longer param to cover missing branch --- test/fixtures/doc.json | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/test/fixtures/doc.json b/test/fixtures/doc.json index a91a836..44478be 100644 --- a/test/fixtures/doc.json +++ b/test/fixtures/doc.json @@ -373,6 +373,10 @@ { "name": "$name", "type": "string" + }, + { + "name": "$nameEvenLonger", + "type": "LongClassName" } ], "return": "void" @@ -381,8 +385,9 @@ "/**", " * ${1:Undocumented function}", " *", - " * @param ${2:int} \\$nameLong ", - " * @param ${3:string} \\$name ", + " * @param ${2:int} \\$nameLong ", + " * @param ${3:string} \\$name ", + " * @param ${4:LongClassName} \\$nameEvenLonger ", " */" ] },