Repository: cschlosser/doxdocgen Branch: master Commit: 28f9c88fa46a Files: 54 Total size: 226.3 KB Directory structure: gitextract_4uo1r0wb/ ├── .github/ │ ├── ISSUE_TEMPLATE/ │ │ ├── bug_report.md │ │ └── feature_request.md │ ├── ISSUE_TEMPLATE.md │ ├── PULL_REQUEST_TEMPLATE.md │ └── workflows/ │ ├── cd.yml │ ├── ci.yml │ └── codeql-analysis.yml ├── .gitignore ├── .nycrc ├── .vscode/ │ ├── launch.json │ ├── settings.json │ └── tasks.json ├── .vscodeignore ├── CHANGELOG.md ├── LICENSE ├── README.md ├── package.json ├── src/ │ ├── CodeParserController.ts │ ├── Common/ │ │ ├── ICodeParser.ts │ │ └── IDocGen.ts │ ├── Config.ts │ ├── DoxygenCompletionItemProvider.ts │ ├── GitConfig.ts │ ├── Lang/ │ │ └── Cpp/ │ │ ├── CppArgument.ts │ │ ├── CppDocGen.ts │ │ ├── CppParseTree.ts │ │ ├── CppParser.ts │ │ └── CppToken.ts │ ├── extension.ts │ ├── templatedString.ts │ ├── test/ │ │ ├── CppTests/ │ │ │ ├── Attributes.test.ts │ │ │ ├── Con-AndDestructor.test.ts │ │ │ ├── Config.test.ts │ │ │ ├── FileDescription.test.ts │ │ │ ├── FunctionPointer.test.ts │ │ │ ├── Operators.test.ts │ │ │ ├── Parameters.test.ts │ │ │ ├── Preprocessor.test.ts │ │ │ ├── ReturnTypes.test.ts │ │ │ ├── SmartText.test.ts │ │ │ ├── Templates.test.ts │ │ │ ├── TestSetup.ts │ │ │ └── TrailingReturns.test.ts │ │ ├── index.ts │ │ ├── runTests.ts │ │ └── tools/ │ │ ├── MockDocument.ts │ │ ├── MockEditor.ts │ │ ├── MockLine.ts │ │ ├── MockPosition.ts │ │ ├── MockSelection.ts │ │ └── MockTextEditorEdit.ts │ └── util.ts ├── tsconfig.json └── tslint.json ================================================ FILE CONTENTS ================================================ ================================================ FILE: .github/ISSUE_TEMPLATE/bug_report.md ================================================ --- name: Bug report about: Create a report to help us improve title: '' labels: bug assignees: '' --- **Describe the bug** A clear and concise description of what the bug is. **Code example** ```Cpp // Put your code here ``` **Expected result** ```Cpp /** * @brief Put the expected comment here */ ``` **Actual result** ```Cpp /** * @brief Put the actually generated comment here */ ``` **Screencaps** If applicable, add screencaps to help explain your problem. **Your System:** - OS: [Windows, macOS, Linux] - VS Code Version [e.g. 1.55] - Doxdocgen Code Version [e.g. 1.3.1] **Additional context** Add any other context about the problem here. ================================================ FILE: .github/ISSUE_TEMPLATE/feature_request.md ================================================ --- name: Feature request about: Suggest an idea for this project title: '' labels: enhancement assignees: '' --- **Is your feature request related to a problem? Please describe.** A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] **Describe the solution you'd like** A clear and concise description of what you want to happen. **Describe alternatives you've considered** A clear and concise description of any alternative solutions or features you've considered. **Additional context** Add any other context or screenshots about the feature request here. ================================================ FILE: .github/ISSUE_TEMPLATE.md ================================================ # Description Anything you'd like to add ## Code example ```Cpp // Put your code here ``` ### Expected result ```Cpp /** * @brief Put the expected comment here */ ``` ### Actual result ```Cpp /** * @brief Put the actually generated comment here */ ``` ================================================ FILE: .github/PULL_REQUEST_TEMPLATE.md ================================================ # Fix/Feature/Other ## Fix - [ ] Link to issue. If there is no issue please describe it using at least the issue template - [ ] Description of the fix - [ ] Added unit test ## Feature - [ ] Description of what's added - [ ] Gif of your feature if appropriate - [ ] Added gif to README - [ ] Added unit test ## Other - [ ] Description ================================================ FILE: .github/workflows/cd.yml ================================================ name: Release on: push: branches: - master pull_request: branches: - master release: types: - created jobs: pipeline: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v2 - name: Use Node.js uses: actions/setup-node@v1 with: node-version: '15.11.0' - run: yarn - name: Install VSCE run: yarn add vsce ovsx -D - name: Update $PATH run: echo "$PWD/node_modules/.bin/" >> $GITHUB_PATH - name: Build vsix run: vsce package && ls -alh - name: Publish to VS Code Marketplace run: vsce publish -p ${VSCE_TOKEN} env: VSCE_TOKEN: ${{ secrets.VSCE_TOKEN }} if: contains(github.ref, 'refs/tags/') - name: Publish to Open VSX Registry run: ovsx publish env: OVSX_PAT: ${{ secrets.OPEN_VSX_TOKEN }} if: contains(github.ref, 'refs/tags/') - name: Upload vsix to GitHub release uses: svenstaro/upload-release-action@v2 with: repo_token: ${{ secrets.GITHUB_TOKEN }} file: doxdocgen-*.vsix tag: ${{ github.ref }} overwrite: true file_glob: true if: contains(github.ref, 'refs/tags/') ================================================ FILE: .github/workflows/ci.yml ================================================ name: CI on: push: branches: [ master ] pull_request: branches: [ master ] jobs: lint: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v2 - name: Use Node.js uses: actions/setup-node@v1 with: node-version: '15.11.0' - run: yarn - name: Lint run: yarn lint build: needs: lint runs-on: ${{ matrix.os }} strategy: matrix: os: [ubuntu-latest, macos-latest, windows-latest] steps: - name: Checkout uses: actions/checkout@v2 - name: Use Node.js uses: actions/setup-node@v1 with: node-version: '15.11.0' - run: yarn - name: Compile run: yarn compile test: needs: build runs-on: ${{ matrix.os }} strategy: matrix: # disable ubuntu-latest until https://github.com/microsoft/vscode/issues/106569 is fixed os: [macos-latest, windows-latest] steps: - name: Checkout uses: actions/checkout@v2 - name: Use Node.js uses: actions/setup-node@v1 with: node-version: '15.11.0' - run: yarn - name: Test run: yarn test # Run tests only on non-coverage job if: matrix.os != 'macOS-latest' - name: Generate Coverage run: yarn cov if: matrix.os == 'macOS-latest' - name: Publish coverage uses: codecov/codecov-action@v1 with: token: ${{ secrets.CODECOV_TOKEN }} if: matrix.os == 'macOS-latest' - name: Upload coverage uses: actions/upload-artifact@v2 with: name: cov path: coverage if: matrix.os == 'macOS-latest' ================================================ FILE: .github/workflows/codeql-analysis.yml ================================================ # For most projects, this workflow file will not need changing; you simply need # to commit it to your repository. # # You may wish to alter this file to override the set of languages analyzed, # or to provide custom queries or build logic. # # ******** NOTE ******** # We have attempted to detect the languages in your repository. Please check # the `language` matrix defined below to confirm you have the correct set of # supported CodeQL languages. # name: "CodeQL" on: push: branches: [ master ] pull_request: # The branches below must be a subset of the branches above branches: [ master ] schedule: - cron: '32 8 * * 3' jobs: analyze: name: Analyze runs-on: ubuntu-latest permissions: actions: read contents: read security-events: write strategy: fail-fast: false matrix: language: [ 'javascript' ] # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python' ] # Learn more: # https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#changing-the-languages-that-are-analyzed steps: - name: Checkout repository uses: actions/checkout@v2 # Initializes the CodeQL tools for scanning. - name: Initialize CodeQL uses: github/codeql-action/init@v1 with: languages: ${{ matrix.language }} # If you wish to specify custom queries, you can do so here or in a config file. # By default, queries listed here will override any specified in a config file. # Prefix the list here with "+" to use these queries and those in the config file. # queries: ./path/to/local/query, your-org/your-repo/queries@main # Autobuild attempts to build any compiled languages (C/C++, C#, or Java). # If this step fails, then you should remove it and run the build manually (see below) - name: Autobuild uses: github/codeql-action/autobuild@v1 # ℹ️ Command-line programs to run using the OS shell. # 📚 https://git.io/JvXDl # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines # and modify them (or add more) to build your code if your project # uses a compiled language #- run: | # make bootstrap # make release - name: Perform CodeQL Analysis uses: github/codeql-action/analyze@v1 ================================================ FILE: .gitignore ================================================ out node_modules .vscode-test/ *.vsix coverage/ .DS_Store /npm-debug.log /.nyc_output/ package-lock.json ================================================ FILE: .nycrc ================================================ { "extends": "@istanbuljs/nyc-config-typescript", "cache": false, "cwd": "./", "exclude": [ "**/**.test.js" ], "extension": [ ".ts", ".tsx" ], "hookRequire": true, "hookRunInContext": true, "hookRunInThisContext": true, "instrument": true, "reporter": ["json", "text"], "recursive": true, "require": [ "ts-node/register", "source-map-support/register" ], "sourceMap": true, "all": true, "include": [ "src/Lang" ] } ================================================ FILE: .vscode/launch.json ================================================ // A launch configuration that compiles the extension and then opens it inside a new window { "version": "0.1.0", "configurations": [ { "name": "Launch Extension", "type": "extensionHost", "request": "launch", "runtimeExecutable": "${execPath}", "args": ["--extensionDevelopmentPath=${workspaceRoot}" ], "stopOnEntry": false, "sourceMaps": true, "outFiles": [ "${workspaceRoot}/out/**/*.js" ], "preLaunchTask": "npm: compile" }, { "name": "Launch Tests", "type": "extensionHost", "request": "launch", "runtimeExecutable": "${execPath}", "args": ["--extensionDevelopmentPath=${workspaceRoot}", "--extensionTestsPath=${workspaceRoot}/out/test", "--disable-extensions" ], "stopOnEntry": false, "sourceMaps": true, "outFiles": [ "${workspaceRoot}/out/test/**/*.js" ], "preLaunchTask": "npm: compile" } ] } ================================================ FILE: .vscode/settings.json ================================================ // Place your settings in this file to overwrite default and user settings. { "files.exclude": { "out": false // set this to true to hide the "out" folder with the compiled JS files }, "search.exclude": { "out": true // set this to false to include "out" folder in search results } } ================================================ FILE: .vscode/tasks.json ================================================ // See https://go.microsoft.com/fwlink/?LinkId=733558 // for the documentation about the tasks.json format { "version": "2.0.0", "tasks": [ { "type": "npm", "script": "watch", "problemMatcher": "$tsc-watch", "isBackground": true, "presentation": { "reveal": "never" }, "group": { "kind": "build", "isDefault": true } } ] } ================================================ FILE: .vscodeignore ================================================ .vscode/** .vscode-test/** out/test/** out/**/*.map src/** .gitignore tsconfig.json vsc-extension-quickstart.md .travis.yml appveyor.yml coverconfig.json publish_coverage.sh .github/** ================================================ FILE: CHANGELOG.md ================================================ # Change Log ## [1.4.0] ### Feature - Use `vscode.workspace.workspaceFolders[0]` to construct SimpleGit instance (#268) Thanks to @lukester1975 ### Fix - Add official VS Code Language identifier for CUDA (#273) Thanks to @jobtijhuis ## [1.3.2] ### Fix - Indent alignment not working in file comments (#206) (#236) Thanks to @HO-COOH - Several typos (#233) Thanks to @jogo- ## [1.3.1] ### Fix - Only suggest Doxygen snippet's when the cursor is in a comment section (#224) (#229) Thanks to @HO-COOH ## [1.3.0] ### Feature - Add `{file}` template, so it can be used in custom tag of both file comments and generic comments (#191) (#221) Thanks to @HO-COOH ## [1.2.2] ### Fix - Fix tags in generic order not expanded (#204) (#217) Thanks to @HO-COOH ## [1.2.1] ### Fix - Fix unexpected return tag on non-functions (#210) (#214) Thanks to @HO-COOH ## [1.2.0] ### Feature - Doxygen command Intellisense support (#211) Thanks to @HO-COOH ### Other - Nicer setting descriptions (#209) Thanks to @HO-COOH ## [1.1.0] ### Feature - Substitute author and email by git config (#186) (#182) Thanks to @to-s ### Other - Update to Typescript 3.8.3 ## [1.0.1] ### Fix - Files without includes don't trigger the autocomplete for file description (#141) (#183) Thanks to @to-s ## [1.0.0] ### Revert - Revert reverting Replace environment variables in templated strings. If no environment variable can be found the name of the variable will be inserted (#110) ### Other - vsce packaging is forcing yarn even if no yarn config exists. Override this behavior now to use npm. ## [0.8.2] ### Other - Package with older version of vsce ## [0.8.1] ### Revert - Replace environment variables in templated strings. If no environment variable can be found the name of the variable will be inserted (#110) ## [0.8.0] ### Feature - Support for arbitrary tags (#169) - Replace environment variables in templated strings. If no environment variable can be found the name of the variable will be inserted (#110) ### Fix - Incorrect parameter name of template (#170) ## [0.7.2] ### Fix - Could not generate correct file header annotation (again) #164 (#161) ## [0.7.1] ### Fix - Could not generate correct file header annotation #162 (#161) ## [0.7.0] ### Feature - Add option to filter keywords (like custom defines) from input line #159 (#152) ### Fix - Argument type would be placed as the param instead of the argument name #154 Thanks to @DaanHuinink - Bug when commenting macros #158 (#142) ## [0.6.0] ### Feature - Add support for multiline template #140 (#127) Thanks to @eternalphane - Enable CUDA language support #148 (#128) Thanks to @trxcllnt ### Other - Update dev dependencies ## [0.5.2] ### Fix - Cannot see params & return value, for global functions (#136) ## [0.5.1] ### Fix - Ignore `restrict` keyword in C function parameter pointer (#121) - Parameters not generated when using custom trigger (#119) - Function argument. Pointer to table is not generated. (#123) ### Other - Update dev dependencies and increase min VS Code version (#131, #132) ## [0.5.0] ### Feature - Feature suggest: Indent option (#107) #### Alignment This version introduces the possibility to align text elements in config strings at a specified width. Example: ```json "doxdocgen.generic.paramTemplate": "@param{indent:10}{param}{indent:30}My Param doc" ``` will turn into ```cpp /** * @param foo My Param doc * @param barIsAlsoAnOption My Param doc */ void bar(int foo, int barIsAlsoAnOption); ``` You can use the `{indent:}` in any templated config option available. Numbers have to be bigger than 0 to have any effect. Alignment will be done from the start of the config string, like this: ```json "doxdocgen.generic.paramTemplate": "@param {param}{indent:14}test" ``` ```cpp /** * @param test */ |<---------->| // 14 ``` ## [0.4.3] ### Fix - Trigger Sequence /** causes extra */ to be generated and the comment block isn't fully generated. (#111) ## [0.4.2] ### Fix - Invalid argument name for C `enum` types (#102) ## [0.4.1] ### Fix - Wrong \param value generation. (#91) ## [0.4.0] ### Feature - Additional file header fields for version, copyright, and custom text (#89) ## [0.3.3] ### Fix - Doesn't parse CPP member pointer names correctly (#78) ## [0.3.2] ### Fix - Cannot read property 'text' of undefined (#79) ## [0.3.1] ### Fix - Don't create a comment while editing an existing comment. (#67) ## [0.3.0] ### Features - Custom Doxygen tag order for methods (#55) - Suggest smart text (#57) For more details see [README.md](https://github.com/christophschlosser/doxdocgen/tree/0.3.0#smart-text) - Config keys are now grouped, see [Config update](#config-update) for changes ### Config update | Old value | New value | Change | |---------------------------------------|----------------------------------------|:--------:| | doxdocgen.generic.triggerSequence | doxdocgen.c.triggerSequence | Category | | doxdocgen.generic.firstLine | doxdocgen.c.firstLine | Category | | doxdocgen.generic.commentPrefix | doxdocgen.c.commentPrefix | Category | | doxdocgen.generic.lastLine | doxdocgen.c.lastLine | Category | | | doxdocgen.c.setterText | Added | | | doxdocgen.c.getterText | Added | | | doxdocgen.c.factoryMethodText | Added | | doxdocgen.generic.newLineAfterTParams | | Removed | | doxdocgen.generic.newLineAfterBrief | | Removed | | doxdocgen.generic.newLineAfterParams | | Removed | | doxdocgen.generic.tparamTemplate | doxdocgen.cpp.tparamTemplate | Category | | | doxdocgen.cpp.ctorText | Added | | | doxdocgen.cpp.dtorText | Added | | doxdocgen.generic.fileTemplate | doxdocgen.file.fileTemplate | Category | | doxdocgen.generic.fileOrder | doxdocgen.file.fileOrder | Category | | | doxdocgen.generic.generateSmartText | Added | | | doxdocgen.generic.splitCasingSmartText | Added | | | doxdocgen.generic.order | Added | ## [0.2.1] - Hotfix. Include moment.js as runtime dependency ## [0.2.0] - Fix #51 - Fix #52 ## [0.1.0] - Fix #40 - Fix #38 - Fix #37 - Fix #36 - Fix #28 - Fix #24 - Implemented support for `noexcept` and `throw` - Implemented support for `constexpr` and `final` - Implemented support for unnamed parameters, this broke in version 0.0.7 - Add new config variable that allows a user to disable the true and false return on bool types and make it behave like a normal type ## [0.0.7] - Fix #31 - Fixed bug where using a different trigger sequence than "*" causes a newline to be added between the comment and the documented entity. ## [0.0.6] - Improve and fix comment generation for several C++ features (#23) (thanks to @rowanG077 again) ## [0.0.5] - Extend customization of generated documentation (#15, #16) (thanks to @rowanG077) - Fix #10 ## [0.0.4] - Fix #9 - Add option to choose if the return type should be included in generated documentation ## [0.0.3] - Add possibility to set comment start indicator to Qt style ## [0.0.2] - Add C parser and generator ## [0.0.1] - Initial release ================================================ FILE: LICENSE ================================================ The MIT License (MIT) Copyright (c) 2017-2021 Christoph Schlosser Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ================================================ FILE: README.md ================================================ # Generate Doxygen Comments in VS Code This VS Code Extensions provides Doxygen Documentation generation on the fly by starting a Doxygen comment block and pressing enter. [![CI build status](https://img.shields.io/github/workflow/status/cschlosser/doxdocgen/CI/master)](https://github.com/cschlosser/doxdocgen/actions/workflows/ci.yml?query=branch%3Amaster) [![Release build status](https://img.shields.io/github/workflow/status/cschlosser/doxdocgen/CD?label=Release)](https://github.com/cschlosser/doxdocgen/actions/workflows/cd.yml?query=event%3Arelease++) [![codecov](https://codecov.io/gh/cschlosser/doxdocgen/branch/master/graph/badge.svg)](https://codecov.io/gh/cschlosser/doxdocgen) [![IRC chat](https://img.shields.io/badge/irc.oftc.net-%23doxdocgen-brightgreen)](https://webchat.oftc.net/?channels=doxdocgen) ## Table of Contents - [Generate Doxygen Comments in VS Code](#generate-doxygen-comments-in-vs-code) - [Table of Contents](#table-of-contents) - [Features](#features) - [Alignment](#alignment) - [Attributes](#attributes) - [Con- and Destructors](#con--and-destructors) - [Extensive customization](#extensive-customization) - [File descriptions](#file-descriptions) - [Function pointers](#function-pointers) - [Operators](#operators) - [Parameters](#parameters) - [Return types](#return-types) - [Smart text](#smart-text) - [Trailing](#trailing) - [Templates](#templates) - [Auto-complete doxygen commands](#auto-complete-doxygen-commands) - [Config options](#config-options) - [Contributors](#contributors) - [Known Issues](#known-issues) - [What's to come](#whats-to-come) ## Features ### Alignment ![Alignment](images/alignment.gif) For how this works, see the [CHANGELOG.md](https://github.com/cschlosser/doxdocgen/blob/master/CHANGELOG.md#alignment) ### Attributes ![Attribute](images/attributes.gif) ### Con- and Destructors ![Constructor](images/ctor.gif) ![Destructor](images/dtor.gif) ### Extensive customization ![options](images/options.gif) ![xml options](images/opts-xml.gif) ![order of commands](images/opt-order.gif) ### File descriptions ![file description](images/file.gif) ### Function pointers ![func_ptr](images/function_ptr.gif) ### Operators ![Operator](images/operator.gif) ![Delete Operator](images/op-delete.gif) ### Parameters ![Simple Parameter](images/param_simple.gif) ![Long Parameter](images/long-param.gif) ### Return types ![Bool return val](images/bool.gif) ![Declaration](images/declaration.gif) ### Smart text ![Smart text CTor](images/smartTextCtor.gif) ![Smart text Custom](images/smartTextCustom.gif) ![Smart text Getter](images/smartTextGet.gif) Supported smart text snippets: * Constructors * Destructors * Getters * Setters * Factory methods Each of them can be configured with its own custom text and you can decide if the addon should attempt to split the name of the method according to its case. #### Trailing ![Trailing return](images/trailing.gif) ### Templates ![Template method](images/template.gif) ![Template class](images/template-class.gif) ### Auto-complete doxygen commands ![Auto complete doxygen](images/doxygen-auto-complete.gif) ## Config options ```jsonc { // The prefix that is used for each comment line except for first and last. "doxdocgen.c.commentPrefix": " * ", // Smart text snippet for factory methods/functions. "doxdocgen.c.factoryMethodText": "Create a {name} object", // The first line of the comment that gets generated. If empty it won't get generated at all. "doxdocgen.c.firstLine": "/**", // Smart text snippet for getters. "doxdocgen.c.getterText": "Get the {name} object", // The last line of the comment that gets generated. If empty it won't get generated at all. "doxdocgen.c.lastLine": " */", // Smart text snippet for setters. "doxdocgen.c.setterText": "Set the {name} object", // Doxygen comment trigger. This character sequence triggers generation of Doxygen comments. "doxdocgen.c.triggerSequence": "/**", // Smart text snippet for constructors. "doxdocgen.cpp.ctorText": "Construct a new {name} object", // Smart text snippet for destructors. "doxdocgen.cpp.dtorText": "Destroy the {name} object", // The template of the template parameter Doxygen line(s) that are generated. If empty it won't get generated at all. "doxdocgen.cpp.tparamTemplate": "@tparam {param} ", // File copyright documentation tag. Array of strings will be converted to one line per element. Can template {year}. "doxdocgen.file.copyrightTag": [ "@copyright Copyright (c) {year}" ], // Additional file documentation. One tag per line will be added. Can template `{year}`, `{date}`, `{author}`, `{email}` and `{file}`. You have to specify the prefix. "doxdocgen.file.customTag": [], // The order to use for the file comment. Values can be used multiple times. Valid values are shown in default setting. "doxdocgen.file.fileOrder": [ "file", "author", "brief", "version", "date", "empty", "copyright", "empty", "custom" ], // The template for the file parameter in Doxygen. "doxdocgen.file.fileTemplate": "@file {name}", // Version number for the file. "doxdocgen.file.versionTag": "@version 0.1", // Set the e-mail address of the author. Replaces {email}. "doxdocgen.generic.authorEmail": "you@domain.com", // Set the name of the author. Replaces {author}. "doxdocgen.generic.authorName": "your name", // Set the style of the author tag and your name. Can template {author} and {email}. "doxdocgen.generic.authorTag": "@author {author} ({email})", // If this is enabled a bool return value will be split into true and false return param. "doxdocgen.generic.boolReturnsTrueFalse": true, // The template of the brief Doxygen line that is generated. If empty it won't get generated at all. "doxdocgen.generic.briefTemplate": "@brief {text}", // The format to use for the date. "doxdocgen.generic.dateFormat": "YYYY-MM-DD", // The template for the date parameter in Doxygen. "doxdocgen.generic.dateTemplate": "@date {date}", // Decide if you want to get smart text for certain commands. "doxdocgen.generic.generateSmartText": true, // Whether include type information at return. "doxdocgen.generic.includeTypeAtReturn": true, // How many lines the plugin should look for to find the end of the declaration. Please be aware that setting this value too low could improve the speed of comment generation by a very slim margin but the plugin also may not correctly detect all declarations or definitions anymore. "doxdocgen.generic.linesToGet": 20, // The order to use for the comment generation. Values can be used multiple times. Valid values are shown in default setting. "doxdocgen.generic.order": [ "brief", "empty", "tparam", "param", "return", "custom", "version", "author", "date", "copyright" ], // Custom tags to be added to the generic order. One tag per line will be added. Can template `{year}`, `{date}`, `{author}`, `{email}` and `{file}`. You have to specify the prefix. "doxdocgen.generic.customTags": [], // The template of the param Doxygen line(s) that are generated. If empty it won't get generated at all. "doxdocgen.generic.paramTemplate": "@param {param} ", // The template of the return Doxygen line that is generated. If empty it won't get generated at all. "doxdocgen.generic.returnTemplate": "@return {type} ", // Decide if the values put into {name} should be split according to their casing. "doxdocgen.generic.splitCasingSmartText": true, // Array of keywords that should be removed from the input prior to parsing. "doxdocgen.generic.filteredKeywords": [], // Substitute {author} with git config --get user.name. "doxdocgen.generic.useGitUserName": false, // Substitute {email} with git config --get user.email. "doxdocgen.generic.useGitUserEmail": false, // Provide intellisense and snippet for doxygen commands "doxdocgen.generic.commandSuggestion": true, // Add `\\` in doxygen command suggestion for better readability (need to enable commandSuggestion) "doxdocgen.generic.commandSuggestionAddPrefix": false, } ``` ## Contributors [Christoph Schlosser](https://github.com/cschlosser) [Rowan Goemans](https://github.com/rowanG077) ## Known Issues [See open bugs](https://github.com/cschlosser/doxdocgen/labels/bug) ## What's to come [See open features](https://github.com/cschlosser/doxdocgen/labels/enhancement) ================================================ FILE: package.json ================================================ { "name": "doxdocgen", "displayName": "Doxygen Documentation Generator", "description": "Let me generate Doxygen documentation from your source code for you.", "version": "1.4.0", "publisher": "cschlosser", "engines": { "vscode": "^1.55.0" }, "categories": [ "Other" ], "badges": [ { "url": "https://img.shields.io/github/workflow/status/cschlosser/doxdocgen/CI/master", "href": "https://github.com/cschlosser/doxdocgen/actions/workflows/ci.yml?query=branch%3Amaster+", "description": "Continous integration" }, { "url": "https://img.shields.io/github/workflow/status/cschlosser/doxdocgen/CD?label=Release", "href": "https://github.com/cschlosser/doxdocgen/actions/workflows/cd.yml?query=event%3Arelease++", "description": "Release pipeline" }, { "url": "https://codecov.io/gh/cschlosser/doxdocgen/branch/master/graph/badge.svg", "href": "https://codecov.io/gh/cschlosser/doxdocgen", "description": "Code coverage" } ], "activationEvents": [ "onLanguage:cuda", "onLanguage:cuda-cpp", "onLanguage:cpp", "onLanguage:c" ], "contributes": { "configuration": { "type": "object", "title": "Doxygen Documentation Generator Settings", "properties": { "doxdocgen.c.triggerSequence": { "description": "Doxygen comment trigger. This character sequence triggers generation of Doxygen comments.", "type": "string", "default": "/**" }, "doxdocgen.c.firstLine": { "description": "The first line of the comment that gets generated. If empty it won't get generated at all.", "type": "string", "default": "/**" }, "doxdocgen.c.commentPrefix": { "description": "The prefix that is used for each comment line except for first and last.", "type": "string", "default": " * " }, "doxdocgen.c.lastLine": { "description": "The last line of the comment that gets generated. If empty it won't get generated at all.", "type": "string", "default": " */" }, "doxdocgen.c.setterText": { "description": "Smart text snippet for setters.", "type": "string", "default": "Set the {name} object" }, "doxdocgen.c.getterText": { "description": "Smart text snippet for getters.", "type": "string", "default": "Get the {name} object" }, "doxdocgen.c.factoryMethodText": { "description": "Smart text snippet for factory methods/functions.", "type": "string", "default": "Create a {name} object" }, "doxdocgen.cpp.tparamTemplate": { "description": "The template of the template parameter Doxygen line(s) that are generated. If empty it won't get generated at all.", "type": "string", "default": "@tparam {param} " }, "doxdocgen.cpp.ctorText": { "description": "Smart text snippet for constructors.", "type": "string", "default": "Construct a new {name} object" }, "doxdocgen.cpp.dtorText": { "description": "Smart text snippet for destructors.", "type": "string", "default": "Destroy the {name} object" }, "doxdocgen.file.fileTemplate": { "description": "The template for the file parameter in Doxygen.", "type": "string", "default": "@file {name}" }, "doxdocgen.file.copyrightTag": { "markdownDescription": "File copyright documentation tag. Array of strings will be converted to one line per element. Can template `{year}`.", "type": [ "array", "string" ], "default": [ "@copyright Copyright (c) {year}" ] }, "doxdocgen.file.versionTag": { "description": "Version number for the file.", "type": "string", "default": "@version 0.1" }, "doxdocgen.file.customTag": { "markdownDescription": "Additional file documentation. Array of strings will be converted to one line per element. Can template `{year}`, `{date}`, `{author}`, `{email}` and `{file}`. You have to specify the prefix.", "type": [ "array", "string" ], "default": [] }, "doxdocgen.file.fileOrder": { "markdownDescription": "The order to use for the file comment. Values can be used multiple times. Valid values are `file`, `author`, `brief`, `version`, `date`, `empty`, `copyright` and `custom`.", "type": [ "array", "string" ], "default": [ "file", "author", "brief", "version", "date", "empty", "copyright", "empty", "custom" ] }, "doxdocgen.generic.includeTypeAtReturn": { "description": "Whether include type information at return.", "type": "boolean", "default": true }, "doxdocgen.generic.boolReturnsTrueFalse": { "markdownDescription": "If this is enabled, the documentation for a `bool` return value will be split into `true` and `false` entries.", "type": "boolean", "default": true }, "doxdocgen.generic.briefTemplate": { "description": "The template of the brief Doxygen line that is generated. If empty it won't get generated at all.", "type": "string", "default": "@brief {text}" }, "doxdocgen.generic.paramTemplate": { "description": "The template of the param Doxygen line(s) that are generated. If empty it won't get generated at all.", "type": "string", "default": "@param {param} " }, "doxdocgen.generic.returnTemplate": { "description": "The template of the return Doxygen line that is generated. If empty it won't get generated at all.", "type": "string", "default": "@return {type} " }, "doxdocgen.generic.linesToGet": { "description": "How many lines the plugin should look for to find the end of the declaration. Please be aware that setting this value too low could improve the speed of comment generation by a very slim margin but the plugin also may not correctly detect all declarations or definitions anymore.", "type": "number", "default": 20 }, "doxdocgen.generic.authorName": { "markdownDescription": "Set the name of the author. Replaces `{author}`.", "type": "string", "default": "your name" }, "doxdocgen.generic.authorEmail": { "markdownDescription": "Set the e-mail address of the author. Replaces `{email}`.", "type": "string", "default": "you@domain.com" }, "doxdocgen.generic.authorTag": { "markdownDescription": "Set the style of the author tag and your name. Can template `{author}` and `{email}`.", "type": "string", "default": "@author {author} ({email})" }, "doxdocgen.generic.dateTemplate": { "description": "The template for the date parameter in Doxygen.", "type": "string", "default": "@date {date}" }, "doxdocgen.generic.dateFormat": { "description": "The format to use for the date.", "type": "string", "default": "YYYY-MM-DD" }, "doxdocgen.generic.generateSmartText": { "description": "Decide if you want to get smart text for certain commands.", "type": "boolean", "default": true }, "doxdocgen.generic.splitCasingSmartText": { "markdownDescription": "Decide if the values put into `{name}` should be split according to their casing.", "type": "boolean", "default": true }, "doxdocgen.generic.order": { "markdownDescription": "The order to use for the comment generation. Values can be used multiple times. Valid values are `brief`, `empty`, `tparam`, `param`, `return`, `custom`, `author`, `date`, `version` and `copyright`.", "type": [ "array", "string" ], "default": [ "brief", "empty", "tparam", "param", "return", "custom" ] }, "doxdocgen.generic.customTags": { "markdownDescription": "Custom tags to be added to the generic order. One tag per line will be added. Can template `{year}`, `{date}`, `{author}`, `{email}` and `{file}`. You have to specify the prefix.", "type": [ "array", "string" ], "default": [] }, "doxdocgen.generic.filteredKeywords": { "description": "Array of keywords that should be removed from the input prior to parsing.", "type": "array", "default": [] }, "doxdocgen.generic.useGitUserName": { "markdownDescription": "Substitute `{author}` with `git config --get user.name`.", "type": "boolean", "default": false }, "doxdocgen.generic.useGitUserEmail": { "markdownDescription": "Substitute `{email}` with `git config --get user.email`.", "type": "boolean", "default": false }, "doxdocgen.generic.commandSuggestion": { "description": "Provide intellisense and snippet for doxygen commands", "type": "boolean", "default": true }, "doxdocgen.generic.commandSuggestionAddPrefix": { "markdownDescription": "Add `\\` in doxygen command suggestion for better readability (need to enable commandSuggestion)", "type": "boolean", "default": false } } } }, "icon": "images/icon.png", "keywords": [ "cpp", "c++", "c", "Doxygen" ], "license": "SEE LICENSE IN LICENSE", "main": "./out/extension", "repository": { "type": "git", "url": "https://github.com/cschlosser/doxdocgen.git" }, "bugs": { "url": "https://github.com/cschlosser/doxdocgen/labels/bug" }, "scripts": { "vscode:prepublish": "yarn compile", "compile": "tsc -p ./", "watch": "tsc -watch -p ./", "test": "yarn compile && node ./out/test/runTests.js", "cov": "yarn clean && nyc yarn test", "lint": "tslint -c tslint.json 'src/**/*.ts'", "clean": "rm -rf coverage .nyc_output out" }, "dependencies": { "env-var": "^4.1.0", "moment": "^2.29.4", "opn": "^5.2.0", "simple-git": "^3.5.0" }, "devDependencies": { "@istanbuljs/nyc-config-typescript": "0.1.3", "@types/mocha": "^5.2.7", "@types/node": "12.7.1", "@types/vscode": "^1.55.0", "decache": "^4.5.1", "glob": "^7.1.6", "handlebars": "^4.7.3", "minimist": ">=1.2.6", "mocha": "^9.1.3", "nyc": "12.0.1", "remap-istanbul": "^0.13.0", "source-map-support": "^0.5.19", "ts-node": "^9.1.1", "tslint": "^5.20.0", "typescript": "^4.2.4", "vscode-test": "^1.5.2", "yargs-parser": ">=13.1.2" } } ================================================ FILE: src/CodeParserController.ts ================================================ import { Disposable, Position, Range, TextDocumentContentChangeEvent, TextEditor, TextLine, window, workspace, } from "vscode"; import CodeParser from "./Common/ICodeParser"; import { Config } from "./Config"; import GitConfig from "./GitConfig"; import CppParser from "./Lang/Cpp/CppParser"; import { inComment } from "./util"; /** * * Checks if the event matches the specified guidelines and if a parser exists for this language * * @export * @class CodeParserController */ export default class CodeParserController { private disposable: Disposable; private cfg: Config; private gitConfig: GitConfig; /** * Creates an instance of CodeParserController * * @memberOf CodeParserController */ public constructor() { const subscriptions: Disposable[] = []; this.gitConfig = new GitConfig(); // Hand off the event to the parser if a valid parser is found workspace.onDidChangeTextDocument((event) => { const activeEditor: TextEditor = window.activeTextEditor; if (activeEditor && event.document === activeEditor.document) { this.cfg = Config.ImportFromSettings(); this.onEvent(activeEditor, event.contentChanges[0]); } }, this, subscriptions); this.disposable = Disposable.from(...subscriptions); } /** * * Disposes of the subscriptions * * @memberOf CodeParserController */ public dispose() { this.disposable.dispose(); } /*************************************************************************** Implementation ***************************************************************************/ private check(activeEditor: TextEditor, event: TextDocumentContentChangeEvent): boolean { if (activeEditor === undefined || activeEditor == null || event === undefined || event.text == null) { return false; } const activeSelection: Position = activeEditor.selection.active; const activeLine: TextLine = activeEditor.document.lineAt(activeSelection.line); const activeChar: string = activeLine.text.charAt(activeSelection.character); const startsWith: boolean = event.text.startsWith("\n") || event.text.startsWith("\r\n"); // Check if enter was pressed. Note the ! if (!((activeChar === "") && startsWith)) { return false; } // Check if currently in a comment block if (inComment(activeEditor, activeSelection.line)) { return false; } // Do not trigger when there's whitespace after the trigger sequence // tslint:disable-next-line:max-line-length const seq = "[\\s]*(" + this.cfg.C.triggerSequence.replace(/[\-\[\]\/\{\}\(\)\*\+\?\.\\\^\$\|]/g, "\\$&") + ")$"; const match: RegExpMatchArray = activeLine.text.match(seq); if (match !== null) { const cont: string = match[1]; return this.cfg.C.triggerSequence === cont; } else { return false; } } private onEvent(activeEditor: TextEditor, event: TextDocumentContentChangeEvent) { if (!this.check(activeEditor, event)) { return null; } const lang: string = activeEditor.document.languageId; let parser: CodeParser; switch (lang) { case "c": case "cpp": case "cuda": case "cuda-cpp": parser = new CppParser(this.cfg); break; default: // tslint:disable-next-line:no-console console.log("No comments can be generated for language: " + lang); return null; } const currentPos: Position = window.activeTextEditor.selection.active; const startReplace: Position = new Position( currentPos.line, currentPos.character - this.cfg.C.triggerSequence.length, ); const nextLineText: string = window.activeTextEditor.document.lineAt(startReplace.line + 1).text; const endReplace = new Position(currentPos.line + 1, nextLineText.length); parser.Parse(activeEditor).GenerateDoc(new Range(startReplace, endReplace), this.gitConfig); } } ================================================ FILE: src/Common/ICodeParser.ts ================================================ import { TextEditor } from "vscode"; import { IDocGen } from "./IDocGen"; export default interface ICodeParser { /** * @param {TextEditor} activeEditor The open active Editor where the event came from */ Parse(activeEditor: TextEditor): IDocGen; } ================================================ FILE: src/Common/IDocGen.ts ================================================ import { Range } from "vscode"; import GitConfig from "../GitConfig"; export interface IDocGen { /** * @brief Generate documentation string and write it to the active editor * @param {Range} rangeToReplace Range to replace with the generated comment. */ GenerateDoc(rangeToReplace: Range, gitConfig: GitConfig); } ================================================ FILE: src/Config.ts ================================================ import { workspace } from "vscode"; // tslint:disable:max-classes-per-file // tslint:disable:max-line-length class C { public static getConfiguration() { return workspace.getConfiguration("doxdocgen.c"); } public triggerSequence: string = "/**"; public firstLine: string = "/**"; public commentPrefix: string = " * "; public lastLine: string = " */"; public getterText: string = "Get the {name} object"; public setterText: string = "Set the {name} object"; public factoryMethodText: string = "Create a {name} object"; } class Cpp { public static getConfiguration() { return workspace.getConfiguration("doxdocgen.cpp"); } public tparamTemplate: string = "@tparam {param} "; public ctorText: string = "Construct a new {name} object"; public dtorText: string = "Destroy the {name} object"; } class File { public static getConfiguration() { return workspace.getConfiguration("doxdocgen.file"); } public fileTemplate: string = "@file {name}"; public copyrightTag: string[] = ["@copyright Copyright (c) {year}"]; public versionTag: string = "@version 0.1"; public customTag: string[] = []; public fileOrder: string[] = ["brief", "empty", "file", "author", "date"]; } class Generic { public static getConfiguration() { return workspace.getConfiguration("doxdocgen.generic"); } public includeTypeAtReturn: boolean = true; public boolReturnsTrueFalse: boolean = true; public briefTemplate: string = "@brief {text}"; public paramTemplate: string = "@param {param} "; public returnTemplate: string = "@return {type} "; public linesToGet: number = 20; public authorName: string = "your name"; public authorEmail: string = "you@domain.com"; public authorTag: string = "@author {author} ({email})"; public dateTemplate: string = "@date {date}"; public dateFormat: string = "YYYY-MM-DD"; public generateSmartText: boolean = true; public splitCasingSmartText: boolean = true; public order: string[] = ["brief", "empty", "tparam", "param", "return"]; public customTags: string[] = []; public filteredKeywords: string[] = []; public useGitUserName: boolean = false; public useGitUserEmail: boolean = false; } export class Config { public static ImportFromSettings(): Config { const values: Config = new Config(); values.C.triggerSequence = C.getConfiguration().get("triggerSequence", values.C.triggerSequence); values.C.firstLine = C.getConfiguration().get("firstLine", values.C.firstLine); values.C.commentPrefix = C.getConfiguration().get("commentPrefix", values.C.commentPrefix); values.C.lastLine = C.getConfiguration().get("lastLine", values.C.lastLine); values.C.getterText = C.getConfiguration().get("getterText", values.C.getterText); values.C.setterText = C.getConfiguration().get("setterText", values.C.setterText); values.C.factoryMethodText = C.getConfiguration().get("factoryMethodText", values.C.factoryMethodText); values.Cpp.tparamTemplate = Cpp.getConfiguration().get("tparamTemplate", values.Cpp.tparamTemplate); values.Cpp.ctorText = Cpp.getConfiguration().get("ctorText", values.Cpp.ctorText); values.Cpp.dtorText = Cpp.getConfiguration().get("dtorText", values.Cpp.dtorText); values.File.fileTemplate = File.getConfiguration().get("fileTemplate", values.File.fileTemplate); values.File.versionTag = File.getConfiguration().get("versionTag", values.File.versionTag); values.File.copyrightTag = File.getConfiguration().get("copyrightTag", values.File.copyrightTag); values.File.customTag = File.getConfiguration().get("customTag", values.File.customTag); values.File.fileOrder = File.getConfiguration().get("fileOrder", values.File.fileOrder); values.Generic.includeTypeAtReturn = Generic.getConfiguration().get("includeTypeAtReturn", values.Generic.includeTypeAtReturn); values.Generic.boolReturnsTrueFalse = Generic.getConfiguration().get("boolReturnsTrueFalse", values.Generic.boolReturnsTrueFalse); values.Generic.briefTemplate = Generic.getConfiguration().get("briefTemplate", values.Generic.briefTemplate); values.Generic.paramTemplate = Generic.getConfiguration().get("paramTemplate", values.Generic.paramTemplate); values.Generic.returnTemplate = Generic.getConfiguration().get("returnTemplate", values.Generic.returnTemplate); values.Generic.linesToGet = Generic.getConfiguration().get("linesToGet", values.Generic.linesToGet); values.Generic.authorTag = Generic.getConfiguration().get("authorTag", values.Generic.authorTag); values.Generic.authorName = Generic.getConfiguration().get("authorName", values.Generic.authorName); values.Generic.authorEmail = Generic.getConfiguration().get("authorEmail", values.Generic.authorEmail); values.Generic.dateTemplate = Generic.getConfiguration().get("dateTemplate", values.Generic.dateTemplate); values.Generic.dateFormat = Generic.getConfiguration().get("dateFormat", values.Generic.dateFormat); values.Generic.generateSmartText = Generic.getConfiguration().get("generateSmartText", values.Generic.generateSmartText); values.Generic.splitCasingSmartText = Generic.getConfiguration().get("splitCasingSmartText", values.Generic.splitCasingSmartText); values.Generic.order = Generic.getConfiguration().get("order", values.Generic.order); values.Generic.customTags = Generic.getConfiguration().get("customTags", values.Generic.customTags); values.Generic.filteredKeywords = Generic.getConfiguration().get("filteredKeywords", values.Generic.filteredKeywords); values.Generic.useGitUserName = Generic.getConfiguration().get("useGitUserName", values.Generic.useGitUserName); values.Generic.useGitUserEmail = Generic.getConfiguration().get("useGitUserEmail", values.Generic.useGitUserEmail); return values; } public readonly paramTemplateReplace: string = "{param}"; public readonly typeTemplateReplace: string = "{type}"; public readonly nameTemplateReplace: string = "{name}"; public readonly authorTemplateReplace: string = "{author}"; public readonly emailTemplateReplace: string = "{email}"; public readonly dateTemplateReplace: string = "{date}"; public readonly yearTemplateReplace: string = "{year}"; public readonly textTemplateReplace: string = "{text}"; public C: C; public Cpp: Cpp; public File: File; public Generic: Generic; constructor() { this.C = new C(); this.Cpp = new Cpp(); this.File = new File(); this.Generic = new Generic(); } } ================================================ FILE: src/DoxygenCompletionItemProvider.ts ================================================ import * as vscode from "vscode"; import { inComment } from "./util"; // tslint:disable:max-line-length /*https://github.com/cschlosser/doxdocgen/issues/30 */ export default class DoxygenCompletionItemProvider implements vscode.CompletionItemProvider { /** * commands are a tuple of */ public static readonly commands: Array<[string, string, string]> = [ /*Special commands */ ["a", "${1:word}", "Display `` in italics"], ["arg", "${1:item-description}", "Generate a simple, non-nested list of arguments"], ["b", "${1:word}", "Display `` in bold"], ["c", "${1:word}", "Display `` using a typewriter font"], ["code", "{.${1:language-id}}\n${2:code}\n@endcode", "Starts a block of code"], // TODO: match end block symbol with trigger character ["copydoc", "${1:link-object}", "Copy a documentation block from the object specified by `` and paste it at the location of the command. The link object can point to a member (of a class, file or group), a class, a namespace, a group, a page, or a file. If the member is overloaded, you should specify the argument types explicitly"], ["copybrief", "${1:link-object}", "Work in a similar way as `@copydoc` but will only copy the brief description, not the detailed documentation"], ["copydetails", "${1:link-object}", "Work in a similar way as `@copydoc` but will only copy the detailed documentation, not the brief description"], ["docbookonly", "$1\n@enddocbookonly", "Start a block of text that only will be verbatim included in the generated DocBook documentation and tagged with `` in the generated XML output"], ["emoji", ":${1:name}:", "Produce an emoji character given its name"], ["startuml", "${1:file} \"${2:caption}\" ${3:size_indication}=${4:size}\n@enduml", "Start a text fragment which should contain a valid description of a PlantUML diagram"], ["e", "${1:word}", "Display `` in italics"], ["em", "${1:word}", "Display `` in italics"], ["endcode", "", "End a block of code"], ["enddocbookonly", "", "End a block of text that was started with `@docbookonly` command"], ["enduml", "", "End a block that was started with `@startuml`"], ["endhtmlonly", "", "End a block of text that was started with a `@htmlonly` command"], ["endlatexonly", "", "End a block of text that was started with a `@latexonly` command"], ["endmanonly", "", "End a block of text that was started with a `@manonly` command"], ["endxmlonly", "", "End a block of text that was started with a `@xmlonly` command"], ["htmlonly", "$1\n@endhtmlonly", "Start a block of text that only will be verbatim included in the generated HTML documentation and tagged with `` in the generated XML output"], ["image", "${1|html,latex,docbook,rtf|} ${2:file} ${3:caption} ${4:${5:size_inidication}=${6:size}}", "Insert an image into the documentation"], ["latexonly", "$1\n@endlatexonly", "Start a block of text that only will be verbatim included in the generated LATEX documentation and tagged with `` in the generated XML output"], ["manonly", "$1\n@manonly", "Start a block of text that only will be verbatim included in the generated MAN documentation and tagged with `` in the generated XML output"], ["li", "${1:item-description}", "Generate a simple, non-nested list of arguments"], ["n", "", "Force a new line"], ["verbatim", "$1\n@verbatim", "Start a block of text that will be verbatim included in the documentation"], ["xmlonly", "$1\n@endxmlonly", "Start a block of text that will be verbatim included in the documentation"], /*Section indicators */ ["attention", "${1:attention text}", "Start a paragraph where a message that needs attention may be entered. The paragraph will be indented. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. Multiple adjacent `@attention` commands will be joined into a single paragraph. The `@attention` command ends when a blank line or some other sectioning command is encountered."], ["author", "${1:author}", "Starts a paragraph where one or more author names may be entered. The paragraph will be indented. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. Multiple adjacent `@author` commands will be joined into a single paragraph. Each author description will start a new line. Alternatively, one `@author` command may mention several authors. The `@author` command ends when a blank line or some other sectioning command is encountered."], ["authors", "${1:list of authors}", "Equivalent to `@author`"], ["brief", "${1:brief description}", "Starts a paragraph that serves as a brief description. For classes and files the brief description will be used in lists and at the start of the documentation page. For class and file members, the brief description will be placed at the declaration of the member and prepended to the detailed description. A brief description may span several lines (although it is advised to keep it brief!). A brief description ends when a blank line or another sectioning command is encountered. If multiple `@brief` commands are present they will be joined."], ["bug", "${1:bug description}", "Starts a paragraph where one or more bugs may be reported. The paragraph will be indented. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. Multiple adjacent `@bug` commands will be joined into a single paragraph. Each bug description will start on a new line. Alternatively, one `@bug` command may mention several bugs. The `@bug` command ends when a blank line or some other sectioning command is encountered."], ["cond", "${1:section label}", "Starts a conditional section that ends with a corresponding `@endcond` command, which is typically found in another comment block"], ["copyright", "${1:copyright description}", "Starts a paragraph where the copyright of an entity can be described. This paragraph will be indented."], ["date", "${1:date description}", "Starts a paragraph where one or more dates may be entered. The paragraph will be indented. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. Multiple adjacent `@date` commands will be joined into a single paragraph. Each date description will start on a new line. Alternatively, one `@date` command may mention several dates. The `@date` command ends when a blank line or some other sectioning command is encountered."], ["deprecated", "${1:description}", "Starts a paragraph indicating that this documentation block belongs to a deprecated entity"], ["details", "${1:description}", "Just like `@brief` starts a brief description, `@details` starts the detailed description. You can also start a new paragraph (blank line) then the `@details` command is not needed."], ["noop", "", "All the text, including the command, till the end of the line is ignored"], ["else", "", "Starts a conditional section if the previous conditional section was not enabled. The previous section should have been started with a `@if`, `@ifnot`, or `@elseif` command."], ["elseif", "${1:section-label}", "Starts a conditional documentation section if the previous section was not enabled. A conditional section is disabled by default. To enable it you must put the section-label after the ENABLED_SECTIONS tag in the configuration file. The section label can be a logical expression build of section names, round brackets, && (AND), || (OR) and ! (NOT). Conditional blocks can be nested. A nested section is only enabled if all enclosing sections are enabled as well."], ["endcond", "", "Ends a conditional section that was started by `@cond`."], ["endif", "", "Ends a conditional section that was started by `@if` or `@ifnot` For each `@if` or `@ifnot` one and only one matching `@endif` must follow."], ["exception", "${1:exception-object} ${2:exception description}", "Starts an exception description for an exception object with name ``. Followed by a description of the exception. The existence of the exception object is not checked. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. Multiple adjacent @exception commands will be joined into a single paragraph. Each exception description will start on a new line. The `@exception` description ends when a blank line or some other sectioning command is encountered"], ["if", "${1:section-label}\n$2\n@endif", "Starts a conditional documentation section. The section ends with a matching `@endif` command. A conditional section is disabled by default. To enable it you must put the section-label after the ENABLED_SECTIONS tag in the configuration file. The section label can be a logical expression build of section names, round brackets, && (AND), || (OR) and!(NOT). If you use an expression you need to wrap it in round brackets, i.e. `@cond(!LABEL1 && LABEL2)`."], ["ifnot", "${1:section-label}", "Starts a conditional documentation section. The section ends with a matching `@endif` command. This conditional section is enabled by default. To disable it you must put the section-label after the ENABLED_SECTIONS tag in the configuration file. The section label can be a logical expression build of section names, round brackets, && (AND), || (OR) and ! (NOT)."], ["invariant", "${1:description of invariant}", "Starts a paragraph where the invariant of an entity can be described. The paragraph will be indented. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. Multiple adjacent `@invariant` commands will be joined into a single paragraph. Each invariant description will start on a new line. Alternatively, one `@invariant` command may mention several invariants. The `@invariant` command ends when a blank line or some other sectioning command is encountered."], ["note", "${1:text}", "Starts a paragraph where a note can be entered. The paragraph will be indented. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. Multiple adjacent `@note` commands will be joined into a single paragraph. Each note description will start on a new line. Alternatively, one `@note` command may mention several notes. The `@note` command ends when a blank line or some other sectioning command is encountered"], ["par", "${1:paragraph title}\n$2", "If a paragraph title is given this command starts a paragraph with a user defined heading. The heading extends until the end of the line. The paragraph following the command will be indented. If no paragraph title is given this command will start a new paragraph. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. The `@par` command ends when a blank line or some other sectioning command is encountered."], ["param", "${1:parameter-name} ${2:description}", "Starts a parameter description for a function parameter with name ``, followed by a description of the parameter. The existence of the parameter is checked and a warning is given if the documentation of this (or any other) parameter is missing or not present in the function declaration or definition. Multiple adjacent `@param` commands will be joined into a single paragraph. Each parameter description will start on a new line. The `@param` description ends when a blank line or some other sectioning command is encountered. Note that you can also document multiple parameters with a single `@param` command using a comma separated list."], ["parblock", "\n$1\n@endparblock", "For commands that expect a single paragraph as argument (such as `@par`, `@param` and `@warning`), the `@parblock` command allows to start a description that covers multiple paragraphs, which then ends with `@endparblock`."], ["endparblock", "", "This ends a block of paragraphs started with `@parblock`."], ["tparam", "${1:template-parameter-name} ${2:description}", "Starts a template parameter for a class or function template parameter with name ``, followed by a description of the template parameter."], ["post", "${1:description of the postcondition}", "Starts a paragraph where the postcondition of an entity can be described. The paragraph will be indented. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. Multiple adjacent `@post` commands will be joined into a single paragraph. Each postcondition will start on a new line. Alternatively, one `@post` command may mention several postconditions. The `@post` command ends when a blank line or some other sectioning command is encountered."], ["pre", "${1:description of the precondition}", "Starts a paragraph where the precondition of an entity can be described. The paragraph will be indented. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. Multiple adjacent `@pre` commands will be joined into a single paragraph. Each precondition will start on a new line. Alternatively, one `@pre` command may mention several preconditions. The `@pre` command ends when a blank line or some other sectioning command is encountered."], ["remark", "${1:remark text}", "Starts a paragraph where one or more remarks may be entered. The paragraph will be indented. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. Multiple adjacent `@remark` commands will be joined into a single paragraph. Each remark will start on a new line. Alternatively, one `@remark` command may mention several remarks. The `@remark` command ends when a blank line or some other sectioning command is encountered."], ["remarks", "${1:remark text}", "Equivalent to `@remark`"], ["result", "${1:description of the result value}", "Equivalent to `@return`"], ["return", "${1:description of the return value}", "Starts a return value description for a function. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. Multiple adjacent `@return` commands will be joined into a single paragraph. The `@return` description ends when a blank line or some other sectioning command is encountered"], ["returns", "${1:description of the return value}", "Equivalent to `@return`"], ["retval", "${1:return value} ${2:description}", "Starts a description for a function's return value with name ``, followed by a description of the return value. The text of the paragraph that forms the description has no special internal structure. All visual enhancement commands may be used inside the paragraph. Multiple adjacent `@retval` commands will be joined into a single paragraph. Each return value description will start on a new line. The `@retval` description ends when a blank line or some other sectioning command is encountered."], ["sa", "${1:reference}", "Starts a paragraph where one or more cross-references to classes, functions, methods, variables, files or URL may be specified. Two names joined by either `::` or `#` are understood as referring to a class and one of its members. One of several overloaded methods or constructors may be selected by including a parenthesized list of argument types after the method name."], ["see", "${1:reference}", "Equivalent to `@sa`"], ["short", "${1:short description", "Equivalent to `@brief`"], ["since", "${1:text}", "This command can be used to specify since when (version or time) an entity is available. The paragraph that follows `@since` does not have any special internal structure. All visual enhancement commands may be used inside the paragraph. The `@since` description ends when a blank line or some other sectioning command is encountered."], ["test", "${1:paragraph describing a test case", "This command can be used to specify since when (version or time) an entity is available. The paragraph that follows `@since` does not have any special internal structure. All visual enhancement commands may be used inside the paragraph. The `@since` description ends when a blank line or some other sectioning command is encountered."], ["throw", "${1:exception-object} ${2:exception description}", "Equivalent to `@exception`"], ["throws", "${1:exception-object} ${2:exception description}", "Equivalent to `@exception`"], ["todo", "${1:paragraph describing what is to be done}", "Starts a paragraph where a `TODO` item is described. The description will also add an item to a separate `TODO` list. The two instances of the description will be cross-referenced. Each item in the `TODO` list will be preceded by a header that indicates the origin of the item."], ["version", "${1:version number}", "Starts a paragraph where one or more version strings may be entered. The paragraph will be indented. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. Multiple adjacent `@version` commands will be joined into a single paragraph. Each version description will start on a new line. Alternatively, one `@version` command may mention several version strings. The `@version` command ends when a blank line or some other sectioning command is encountered."], ["warning", "${1:warning message}", "Starts a paragraph where one or more warning messages may be entered. The paragraph will be indented. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. Multiple adjacent `@warning` commands will be joined into a single paragraph. Each warning description will start on a new line. Alternatively, one `@warning` command may mention several warnings. The `@warning` command ends when a blank line or some other sectioning command is encountered."], ["xrefitem", "${1:key} \"${2:heading}\" \"${3:list title}\" ${4:text}", "This command is a generalization of commands such as `@todo` and `@bug`. It can be used to create user-defined text sections which are automatically cross-referenced between the place of occurrence and a related page, which will be generated. On the related page all sections of the same type will be collected."], /*Commands to create links */ ["addindex", "${1:text}", "This command adds `text` to the LATEX, DocBook and RTF index."], ["anchor", "${1:word}", "This command places an invisible, named anchor into the documentation to which you can refer with the `@ref` command."], ["cite", "${1:label}", "Adds a bibliographic reference in the text and in the list of bibliographic references. The `