diff --git a/CHANGELOG.md b/CHANGELOG.md index 6056451..d333de1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## 1.1.3 (2022/02/22) +* Added support to add in @author as a signature for a class +* Added an option for align the name of parameters of a method + +## 1.1.2 (2020/06/10) +* Added support to add in @author, @copyright as a signature for a function. +* Also added in a feature for displaying date of creation of the comment. With location + ## 1.1.1 (2020/06/10) * Added support for functions that are not within a class diff --git a/README.md b/README.md index 4b79304..03de1f7 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,17 @@ -# PHPDoc Generator +# Note +This is a fork of the original [repo](https://github.com/ronvanderheijden/vscode-phpdoc-generator) and contains features of this other [fork](https://github.com/Samuel-Hinchliffe/vscode-phpdoc-generator.git) + +I added this new features : + - Added support to add in @author as a signature for a class + - Added an option to align the name of parameters of a method +# A quick note +This is a fork of the original repo. All this app does is a few little things ontop. See the [original](https://marketplace.visualstudio.com/items?itemName=ronvanderheijden.phpdoc-generator) app and also checkout the github [repo](https://github.com/ronvanderheijden/vscode-phpdoc-generator) too. -[![Installs](https://img.shields.io/visual-studio-marketplace/v/ronvanderheijden.phpdoc-generator)](https://marketplace.visualstudio.com/items?itemName=ronvanderheijden.phpdoc-generator) +# What's new about this? +Now every function you generate can have a signature. You can have a @author signature for each function. You can @copyright for each function. Both with a @see signature so you can direct people towards a link. As well as having a snippet of code that will also display when the comment was generated. + +![Screen Capture in Action](https://raw.githubusercontent.com/Samuel-Hinchliffe/vscode-phpdoc-generator/master/assets/example.png) +# PHPDoc Generator PHPDoc Generator is [a VSCode extension](https://marketplace.visualstudio.com/items?itemName=ronvanderheijden.phpdoc-generator) that generates a PHP documentation block using a keyboard shortcut. diff --git a/assets/example.png b/assets/example.png new file mode 100644 index 0000000..992d4a4 Binary files /dev/null and b/assets/example.png differ diff --git a/lib/docBlockGenerator.js b/lib/docBlockGenerator.js index 081a05b..0634565 100644 --- a/lib/docBlockGenerator.js +++ b/lib/docBlockGenerator.js @@ -11,8 +11,12 @@ class DocBlockGenerator { * @return {string} */ static generateClassDocBlock(doc) { + let author = config.get('author'); let docBlock = '/**\r\n'; docBlock += ` * [Description ${doc.getName()}]\r\n`; + if (author !== '') { + docBlock += ` *\r\n * @author ${author}\r\n`; + } docBlock += ` */\r\n`; return docBlock; @@ -92,12 +96,15 @@ class DocBlockGenerator { const shortType = config.get('shortType'); /** @var {boolean} indentAfterParameters */ const indentAfterParameters = config.get('insertIndentAfterParameters'); + /** @var {boolean} alignParametersName */ + const alignParametersName = config.get('alignParametersName'); /** @var {boolean|string} constructorWithType */ const constructorWithType = config.get('constructorWithType'); /** @var {string} indent */ const indent = doc.getIndent(); let docBlock = indent + '/**\r\n'; + let space = ' '; if (config.get('insertDescription')) { docBlock += indent + ` * [Description for ${doc.getName()}]\r\n`; @@ -115,14 +122,22 @@ class DocBlockGenerator { /** @var {string[]} types */ let types; + let maxLen = 0; for (let parameter of parameters) { types = !shortType ? converter.convertTypes(parameter.types) : parameter.types ; + parameter.strTypes = types.join('|'); + maxLen = (parameter.strTypes.length > maxLen) ? parameter.strTypes.length : maxLen; + } + + let strSpaces = ''; - docBlock += indent + ` * @param ${types.join('|')} ${parameter.name}\r\n`; + for (let parameter of parameters) { + strSpaces = (alignParametersName) ? space.repeat(maxLen - parameter.strTypes.length) : ''; + docBlock += indent + ` * @param ${parameter.strTypes} ${strSpaces}${parameter.name}\r\n`; } } @@ -141,17 +156,69 @@ class DocBlockGenerator { } if (indentAfterParameters && doc.hasParameters() && typesOfMethod.length) { - docBlock += indent + ` * \r\n`; + docBlock += indent + ` *\r\n`; } if (typesOfMethod.length) { docBlock += indent + ` * @return ${typesOfMethod.join('|')}\r\n`; } + let alreadyAdded = false; + let maxLengthOtherTag = 0; + let strSpacesOther = ''; + + if (config.get('authorTag')) { + maxLengthOtherTag = "author".length + } + if (config.get('copyrightCompanyName')) { + maxLengthOtherTag = "copyright".length + } + + if (config.get('displayCreationDate')) { + let currentTime = new Date().toLocaleString(); + let timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone + docBlock = DocBlockGenerator.addEmtyLineComment(docBlock, indent); + alreadyAdded = true; + docBlock += indent + ` * Created at: ${currentTime} (${timeZone})\r\n`; + } + + if (config.get('authorTag')) { + docBlock = (!alreadyAdded) ? DocBlockGenerator.addEmtyLineComment(docBlock, indent) : docBlock; + alreadyAdded = true; + strSpacesOther = space.repeat(maxLengthOtherTag - "author".length); + docBlock += indent + ` * @author ${strSpacesOther}${config.get('authorTag')}\r\n`; + } + + if (config.get('authorSeeUrl')) { + docBlock = (!alreadyAdded) ? DocBlockGenerator.addEmtyLineComment(docBlock, indent) : docBlock; + alreadyAdded = true; + strSpacesOther = space.repeat(maxLengthOtherTag - "see".length); + docBlock += indent + ` * @see ${strSpacesOther}{@link ${config.get('authorSeeUrl')}}\r\n`; + } + + if (config.get('companySeeUrl')) { + docBlock = (!alreadyAdded) ? DocBlockGenerator.addEmtyLineComment(docBlock, indent) : docBlock; + alreadyAdded = true; + strSpacesOther = space.repeat(maxLengthOtherTag - "see".length); + docBlock += indent + ` * @see ${strSpacesOther}{@link ${config.get('companySeeUrl')}}\r\n`; + } + + if (config.get('copyrightCompanyName')) { + docBlock = (!alreadyAdded) ? DocBlockGenerator.addEmtyLineComment(docBlock, indent) : docBlock; + alreadyAdded = true; + strSpacesOther = space.repeat(maxLengthOtherTag - "copyright".length); + docBlock += indent + ` * @copyright ${strSpacesOther}${config.get('copyrightCompanyName')}\r\n`; + } + docBlock += indent + ` */\r\n`; return docBlock; } + + static addEmtyLineComment(docBlock, indent) { + const newEmptyLineComment = indent + ` *\r\n`; + return docBlock += newEmptyLineComment; + } } module.exports = DocBlockGenerator; diff --git a/package.json b/package.json index 213d778..94f5c9f 100644 --- a/package.json +++ b/package.json @@ -1,13 +1,13 @@ { "name": "phpdoc-generator", "displayName": "PHPDoc Generator", - "description": "PHPDoc Generator is a VSCode extension that generates a documentation block using a keyboard shortcut.", + "description": "PHPDoc Generator is a VSCode extension that generates a documentation block using a keyboard shortcut. Note: This is a fork of the original. Just with a few extra features. You can have a signature on every function for example", "license": "MIT", "author": { "name": "Ron van der Heijden", "email": "me@ronvanderheijden.nl" }, - "version": "1.1.1", + "version": "1.1.3", "publisher": "ronvanderheijden", "engines": { "vscode": "^1.18.0" @@ -18,6 +18,7 @@ ], "keywords": [ "php", + "php docs", "phpdoc", "phpdoc-generator", "generator", @@ -33,6 +34,11 @@ "configuration": { "title": "PHPDoc Generator", "properties": { + "phpdoc-generator.author": { + "type": "string", + "default": "", + "description": "Add's @author tag to class" + }, "phpdoc-generator.insertDescription": { "type": "boolean", "default": true, @@ -43,6 +49,16 @@ "default": true, "description": "Inserts the indent after parameters." }, + "phpdoc-generator.alignParametersName" : { + "type": "boolean", + "default": true, + "description": "Align the name of each parameter." + }, + "phpdoc-generator.displayCreationDate" : { + "type": "boolean", + "default": false, + "description": "Displays Creation date on a method" + }, "phpdoc-generator.returnUndefinedType": { "type": "string", "default": "[type]", @@ -64,6 +80,22 @@ ], "description": "Specifies the value of a type for @var when it is undefined." }, + "phpdoc-generator.authorTag": { + "type": "string", + "description": "Add's @author tag to the method" + }, + "phpdoc-generator.authorSeeUrl": { + "type": "string", + "description": "Add's a @see tag to a url below the author tag for the method. For instance, @see https://github.com/" + }, + "phpdoc-generator.companySeeUrl": { + "type": "string", + "description": "Add's a @see tag to a url near the copyright tag for the method. For instance, @see https://github.com/" + }, + "phpdoc-generator.copyrightCompanyName": { + "type": "string", + "description": "Add's @copyright tag to the method" + }, "phpdoc-generator.shortType": { "type": "boolean", "default": true, @@ -126,7 +158,7 @@ }, "repository": { "type": "git", - "url": "https://github.com/ronvanderheijden/vscode-phpdoc-generator.git" + "url": "https://github.com/Bruno86/vscode-phpdoc-generator.git" }, "__metadata": { "publisherDisplayName": "ronvanderheijden"