Use parameters data from actual code when jsdoc is used

[phobos2077]

Screenshot

What's wrong on screenshot

• If you add jsdoc comment but omit some arguments, they disappear from the argument list in the hint.
• If you have default value in code itself, it is not reflected in the hint, you have to duplicate this information in the jsdoc

Code

/**
 * Adds one recipe item for a given crafted item, if it doesn't exist. If recipe is known, deletes the item.
 * 
 * @arg {int} schematicPid - PID of schematic item to create
 * @arg {int} probability - % probability of spawn, if conditions are met.
 */
procedure check_restock_craft_schematic(variable schematicPid, variable craftedItemPid, variable probability := 100) begin
end

[phobos2077]

Would also be nice to parse and display comment after @ret

[burner1024]

I don't like duplication. But I also don't like mixing info from different sources. I think it can get too complicated for too little gain. Need to think about it. Maybe make an exception for default values, but I definitely don't want to merge argument lists. Although trusting just one source seems more reliable still.

For functions with return values, the description of those is usually the first thing in the body of the docstring. So, not sure if that's any benefit.

[phobos2077]

But I also don't like mixing info from different sources. I think it can get too complicated for too little gain.

Simple idea: if there's not a single @arg in comment, then you just take data from code (and put any as type). Otherwise trust the @args. This should fix the common case where you just want to put some description without writing out every arg.

For functions with return values, the description of those is usually the first thing in the body of the docstring. So, not sure if that's any benefit.

It's just a simple readability improvement - you see return value described after arguments, like it usually is in documentation.

[burner1024]

It's just a simple readability improvement - you see return value described after arguments, like it usually is in documentation.

Usually... where? Because this is what I usually see

[burner1024]

For args, I think default form will do

[burner1024]

If there's nothing to add about ret, I guess that'll be all.

[phobos2077]

If there's nothing to add about ret, I guess that'll be all.

I mean, it would still be useful to be able to describe return value. But it's not as critical.

[burner1024]

I showed how it's usually described in my experience. If your experience differs, feel free to share.

[phobos2077]

If your experience differs, feel free to share.

Well I come from C# background. There comments have a structure with return value having it's own tag that describes what is returned separately.

As I said, it's not very important, but a feature you would expect when writing structured comments. Why args have comment but ret does not? Feels inconsistent.