This looks like yet another undocumented syntax…
Is this all thread a big misunderstanding because of undocumented features?
Will this thread be the only place where people will learn that {Type} is not mandatory?
Seems like an essential piece of information missing from the docs…
My conclusion is that the exact syntax and behavior of JSDocs should be thoroughly documented in the Wiki (in a page of its own and not only buried in the “New in this release” page for Servoy 6).
What david does is just Doc, the parser just ignores it, assertInstanceId is not suddenly a string there…
So its not a undocumented syntax or feature, its just basic javascript that you can have docs in various places.
I personally would have done: /String/ (so not /** ) because this is more just doc not really JSDoc
Did we document that {Type} is mandatory? (then we should remove that)
i know we did point to this in our wiki:
ptalbot:
My conclusion is that the exact syntax and behavior of JSDocs should be thoroughly documented in the Wiki (in a page of its own and not only buried in the “New in this release” page for Servoy 6).
make a feature request, but i don’t know if you really should do this, but i guess a button could be made to toggle between ignore and warning for everything…
You have “restore to defaults” button in the preferences. Another one to turn them all off so it doesn’t take 5 minutes to click through each option.
jcompagner:
david:
update jsdoc automatically when adding a param to a current method (you do this already for new methods)
We should just do that when saving? or should it just be a quick fix so that developers know what happens?
Quick fix gets my vote.
jcompagner:
david:
“open in script editor” and “open in form editor” shortcut keys for mac back to servoy 5 shortcuts (use the command key instead of cntrl key)
this is one i don’t get, it is configured like: M1+M2+A in the plugin
And M1 stands for Command on the mac or Ctrl on windows…
So it should be Command-Shift-A for you on the mac…
You can always change the keybindings the way you want, just open the preferences and filter on “keys”.
Definitely a mac bug then. It is Cntrl-Shift-Z to open the method editor.
Can you clarify reasoning on the use of JSDoc tags to enforce scope and functionality? Specifically @AllowToRunInFind, @Private, and @protected. These tags go beyond documentation…
david:
Can you clarify reasoning on the use of JSDoc tags to enforce scope and functionality? Specifically @AllowToRunInFind, @Private, and @protected. These tags go beyond documentation…
But @AllowToRunInFind is a special Servoy doc tag. This is the replacement of “controller.search” in side your code to be able to execute the method in find mode
Now we just generate @AllowToRunInFind in side your code where you use controller.search
I guess in a next version of servoy we don’t want to do that anymore (then you have to specify it yourself) and then that is the only tag that allows a method to run in find mode (but this would break old solutions that are never touched by a servoy release that would add @allowtoruninfind to those methods…)
@Private is for making variables and functions private for the scope they are in, So if you have a form that then you can make most form variables and functions @private, because most of them are really used only by the form.
So that if others are forms.yourform. they don’t see your private variables and functions… So your API of your form is much cleaner.
If you would make a module that has some forms that can be used by 3th parties (can be your self) and that has some forms where you have some nice public methods they can call on, then you can hide all other methods from the API that you use internally
@Protected is the same except that those can be seen and used by a sub form, so they are only private for the form and its subforms.
Those private and protected tags are ofcourse only in the editor. at runtime they can be called from the outside world… Because that is just how javascript works.
So it is just a documentation thing and the editor hides them in the code completion and the parser will generate warnings when you do use them.
Well I for one am happy that all this seems to be a misunderstanding of the JSDoc feature and that it’s not the real problem we thought it to be.
So I understand from Johan that JSDoc is in fact completely optional. In fact you could even skip it and things will still keep working other than the obvious things like code completion on things that are dynamically declared using string and/or variables so the parser doesn’t know what it is.
So the warnings are just there to make sure you catch any flaws/bugs or bad coding practices in the same manner JSLint would do this. But if we want we could simply switch these warnings off in a granular manner.
By the way this needs to be done in the ‘Preferences > JavaScript > Errors/Warnings’ and not in places like the Problems view, Markers view or the Servoy Warnings prefs (where I was looking for it).
As for the JSDoc documentation it does pretty much state that the type expression is mandatory so that should be updated. Preferably explicitly stating that it’s an optional parameter.
But one thing I like to have off my chest.
I really appreciate Servoy for having this forum and I also understand that it’s community driven. It’s not an official channel for Servoy support (it’s best effort), there are other channels for that (Jira for bugs & features and customers can get an SLA for immidiate support).
But this thread has been going on for at least a week where 1 response from Servoy (like Johan did) would have nipped it in the butt. But instead it was allowed to fester for this long.
It might even have gone on longer if I hadn’t poked Johan via other channels. And now I learned he was in fact on vacation last week.
I sure hope more Servoy engineers are monitoring this forum (and yes I know…it’s best effort, i.e. if they have time for it).
In any case, thank you Johan for clearing this up.
Yes Robert, you are right, it’s great that this is just a misunderstanding.
Looking at the JSDoc documentation you point on (and that I failed to find previously), I read: “The tag must be followed by a Type Expression and a name”, which clearly means that it is mandatory.
So once again, bad documentation leads to misunderstanding and hair pulled for no good reason.
This is an important ‘feature’ IMHO and this should be crystal clear in the doc.
And yes, thanks Johan for taking the time to explain!
We certainly appreciate your ‘best effort’!
jcompagner:
Those private and protected tags are ofcourse only in the editor. at runtime they can be called from the outside world… Because that is just how javascript works.
So it is just a documentation thing and the editor hides them in the code completion and the parser will generate warnings when you do use them.
Cool, was wondering how much scoping was “enforced” with those. Only an editor thing works for me. Not so sure I like @AllowToRunInFind though. Using JSDoc to trigger functionality reminds me of compiler directives.
yes i had a week off, a week with very little laptop time!
@AllowToRunInFind is way better “annotation” like we have also in java for stuff to enable it, then depending on if “controller.search” is in the code!
We need more like those like which global methods can be called from a deeplink like @deeplinkmethod, so all those things are opt ins
Patrick as i said i already changed the jsdoc page quite some time ago, but it is never published (and i can’t do that)
but this is the description:
"
Describe function parameters.
The tag can be followed by a Type Expression between {} and must have a name.
The “name” must match the name of one of the parameters in the function declaration.
If you are passing in an unknown Java Object (so not a javascript object) or you don’t want to have any type information on that parameter, you shouldn’t use a type expressing but just the name and some extra doc about this parameter.
"
jcompagner:
yes i had a week off, a week with very little laptop time!
Ah, that was the problem then!
jcompagner:
Patrick as i said i already changed the jsdoc page quite some time ago, but it is never published (and i can’t do that)
but this is the description:
"
Describe function parameters.
The tag can be followed by a Type Expression between {} and must have a name.
The “name” must match the name of one of the parameters in the function declaration.
If you are passing in an unknown Java Object (so not a javascript object) or you don’t want to have any type information on that parameter, you shouldn’t use a type expressing but just the name and some extra doc about this parameter.
"
Great thanks! Now let’s hope the people in charge of pushing the publish button in the wiki will do their work soon as well…
jcompagner: @AllowToRunInFind is way better “annotation” like we have also in java for stuff to enable it, then depending on if “controller.search” is in the code!
We need more like those like which global methods can be called from a deeplink like @deeplinkmethod, so all those things are opt ins
Have to use custom JSDocs tags to do these things though? JSDocs are for documentation, not controlling things. End result is muddying up JSDocs and the controlling commands.
yes and that is way better @private or @deprecated is the same thing
You can’t have direct annotation in the code, that is not supported
You just describe what the method should do in those things, Its they only way and a user knows directly from the doc that this method can be executed in find…
I see what you are trying to do but I think docs should only be a reflection of what your code is and no more—not used to drive aspects of your code as well. Using JSDocs to add in Servoy IDE specific features seems a bit weird to me and I don’t like the direction it is leading. Kind of why this whole thread started in the first place—the perception was that Servoy was using JSDocs to enforce variable typing.
Well, turns out Servoy is in fact using JSDocs to control some things. JSDocs as a result is “muddied up”. They are harder for us to understand and use.
I think IDE specific control stuff (meta data if you will) should be somewhere else. Then generate/quick fix the JSDoc to reflect the control parameters that are set somewhere else.
that is not really weird
Java was exactly the same, there you also has @deprected and so on.
Nowadays we have really annotations for thats really in the source code instead of the docs (from java 5 on)
But jsdoc is the perfect place for that, because it also should be "doc’ed’ any way. (like deprecation or allowed in find or that it is a deeplink method, those should be documented also)
Having those things in a completely different place stored is just weird and error prone .
pbakker:
And to add to that: you can configure all the warnings on a project to project basis already, by selecting the option at the top of the Preference page where you do all the settings, called “Configure Project Specific Settings”
gdurniak:
We just upgraded from Servoy 3 to 6, and got hit in the face by this JSDocs thing … from page 3 of this thread, it seems I can just turn off the warnings, and ignore all this, but is this advice documented anywhere else ?
If so, I missed it
thanks
greg
Greg,
It’s of course recommended that you don’t just turn off the warnings. Specially because you are upgrading from Servoy 3. But it all depends on the time constraint of your project.
Hopefully you are upgrading to Servoy 6.1 (some further annoyance were removed and don’t appear in 6.1). If you are willing to clean all those warnings, make sure that you upgraded to 6.1