View Issue Details

IDProjectCategoryView StatusLast Update
0019002MMW 5Help / Docs / Localizationpublic2022-05-12 21:18
Reporterzvezdan Assigned To 
PriorityurgentSeverityminorReproducibilityN/A
Status closedResolutionfixed 
Product Version5.0.3 
Target Version5.0.3Fixed in Version5.0.3 
Summary0019002: JSDoc comments in scripts are unuseful and incorect
DescriptionI 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.
TagsNo tags attached.
Fixed in build2617

Activities

drakinite

2022-04-24 04:45

developer   ~0067697

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.

zvezdan

2022-04-24 05:50

updater   ~0067700

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.

drakinite

2022-04-25 01:13

developer   ~0067747

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.

peke

2022-05-12 21:18

developer   ~0068128

Revised along with 2624 no regressions found/reported till 2622 public build at day of review.

Rest is tracked in 0019015