View Issue Details
| ID | Project | Category | View Status | Date Submitted | Last Update |
|---|---|---|---|---|---|
| 0019002 | MMW 5 | Help / Docs / Localization | public | 2022-04-22 23:21 | 2022-05-12 21:18 |
| Reporter | zvezdan | Assigned To | |||
| Priority | urgent | Severity | minor | Reproducibility | N/A |
| Status | closed | Resolution | fixed | ||
| Product Version | 5.0.3 | ||||
| Target Version | 5.0.3 | Fixed in Version | 5.0.3 | ||
| Summary | 0019002: JSDoc comments in scripts are unuseful and incorect | ||||
| Description | I don't know which standard you followed, it is not JSDoc, nor TypeScript or Google Closure variant. In many cases you have something like: @param fn {Function} Function to be called... while it should be: @param {Function} fn Function to be called... The type of parameter should be specified before its name. Or, you have something like: @param {String or Array} files Here you have the order right, but JSDoc doesn't have "or" operator. It should be: @param {(string|string[])} files as it is mentioned in examples at https://jsdoc.app/tags-param.html. The VSCode doesn't have IntelliSense at all because of your missing/incorrect JSDoc comments, its Go to Definition also doesn't work because of your comments. You should open your script files in it, and add this to its settings.json: "js/ts.implicitProjectConfig.checkJs": true, and then you will see how many errors will be reported with them. You are ignoring the most popular text editor for programmers and its capabilities. | ||||
| Tags | No tags attached. | ||||
| Fixed in build | 2617 | ||||
|
|
We are using Yuidoc. It is parsed by YuidocJS to https://www.mediamonkey.com/docs/api/. I initially wanted to rewrite our documentation comments into JSDoc, but JSDoc is also old and no longer regularly maintained. I am slowly working on TypeScript documentation modules (*.d.ts) which should be able to give IntelliSense autocompletion when people add those typescript files to their project folder. |
|
|
You should use what is good for scripters, not what is good and easier for you. Your web MM5 API is useless. It is nowhere near as organized and efficient as MM4 API. I actually more discovered by analyzing the included JavaScripts than reading your API. Um, wait. I though this is about another issue. Anyway, they are related, since your API is just based on those poorly written Yuidoc comments. I didn't suggest that you use JSDoc. You should use TypeScript variant since it is used in VSCode (https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html). Just download VSCode source code and open its files to see how look good commented source code. You will get a proper Go to Definition and you will see almost none error in them. |
|
|
Bulk updated the JS documentation comments to fix the invalid JSDoc syntax (e.g. @param fn {Function}). Tracking the TS documentation modules in 0019015, as it will be a long task to complete and is not related to this issue. I am already using the // @ts-check method to assist with creating those .d.ts files. |
|
|
Revised along with 2624 no regressions found/reported till 2622 public build at day of review. Rest is tracked in 0019015 |
