[kylemwhite]

@claudiobosticco: Yes, Visual Studio shows the documentation for properties and methods including parameters. Here's a few screenshots:






I have learned, however, that it does not support all JSDoc tags. For example, the @deprecated and @link tags don't seem to work. I've included the @deprecated tags (as well as the word DEPRECATED in the description) anyway in hopes that it works for other (or future VS) IDEs and because it doesn't mess up anything in VS (they just don't show up). The @link tags look ugly in VS so I've left them out for now. To help me make it better for IntelliJ, please try the following:

1. If you're using another TypeDef library that works properly, let me know what it is and/or post some code that shows the comments for a property and method. If not, please check out the tags at http://usejsdoc.org and tweak the code in one of my files. If you find the magic format to make it work in your IDE, let me know what it is. That way I can tune the generator to output the same format.

2. Try using a deprecated property/method and see if the @deprecated tag is doing anything. There's a bunch in DateStatic (isc.Date.compareDates() etc.) because they've moved that functionality to the DateUtil class.

Thanks for the feedback!

[claudiobosticco]

Hello kylemwhite, using IntelliJ I've got completion and documentation for classes, but for attributes and methods I've got only completion but no documentation.
Does VisualStudio show documentation for attributes and methods also?

[Isomorphic]

Yes, SmartGWT is generated from referenceDocs.xml, plus a (shrinking) number of manual additions.

We'll go ahead and officially doc the SC getDataSource() API, which may as well be public.

[kylemwhite]

@Blama: Well, that makes sense then because my first Isomorphic project was with SmartGWT and I probably copied a lot of code. As I understand it, the SmartGWT framework and docs are generated from the same file I'm using but I don't know how stuff like that gets added.

[Blama]

because it is not in the referenceDocs.xml file and doesn't show up in the online Docs. I don't know how I even know of this method, probably it was in a sample somewhere. Is this a supported method that should be in the docs? (please say 'yes').

Interestingly it is in the SmartGWT docs, so I assume it will be fine.
Isomorphic: Out of interest: From this thread I get that the SmartGWT source and docs is generated from the file, kylemwhite uses for his Typescript definition, plus some (many?) manual additions, like this one now. Is that correct?

Best regards
Blama

[kylemwhite]

There is an instance method on ListGrid called getDataSource() which returns a DataSource object. I've been using this method for years and it works. However, the TypeScript generator is not creating it because it is not in the referenceDocs.xml file and doesn't show up in the online Docs. I don't know how I even know of this method, probably it was in a sample somewhere. Is this a supported method that should be in the docs? (please say 'yes').

[kylemwhite]

Thanks, there are 18 others (suspected) as I point out in the Errors.txt file.

New code based on SNAPSHOT_v11.1d_2017-05-10 uploaded. Added DEPRECATED and @deprecated tags appropriately, added @return tags, added interfaces file, better formatted descriptions, refined validation rules, generated more interfaces, classes, objects and methods.

Changed the description of the optional parameter rule to "Suspected optional parameters that are marked with optional='false'" because I think the previous description was causing confusion.

[Isomorphic]

That's an instance where the param should be marked optional=true, and we'll fix this one. Let us know if you see any others.

[kylemwhite]

I wasn't planning on having the generator create any code based on anything in any description, that would be silly. I'm just using the description to try to determine if a parameter was supposed to be marked optional='true' but got missed.

Parameters marked optional can be completely omitted, like a different method signature in Java. For example, if the last parameter of a 3-argument method is optional, you can call it with two arguments.

I think you're saying the same thing as me. For example, the Messaging.subscribe classMethod has 4 parameters. The last one is optional (according to the description), which means it can be omitted. However, that parameter is not marked with optional='true' in the docs.

<docItem ref="classMethod:Messaging.subscribe" type="classMethod" definingClass="class:Messaging" description=" Subscribes the client to the messaging channel identified by channel.&amp;#010 &lt;p&gt;&amp;#010 When the server or another connected browser sends a message on this channel, the callback &amp;#010 will be invoked with a single 'data' parameter containing the data that was just sent to the&amp;#010 channel.&amp;#010 &lt;p&gt;&amp;#010 Calling subscribe() again for a channel you are already subscribed to will result in the new&amp;#010 callback replacing the old, and will cause the server connection to be re-established.&amp;#010&amp;#010" flags="" name="subscribe">
    <groups>messaging</groups>
<params optional="false" type="String" name="channel">
</params>
<params optional="false" type="MessagingCallback" description="callback fired whenever data is sent to this channel" name="callback">
</params>
<params optional="false" type="Callback" description="callback fired when the subscription is established" name="subscribeCallback">
</params>
<params [B]optional="false"[/B] type="String" description="JMS selector used with Queues to filter the messages
that arrive  to the channel [B](optional)[/B]." name="selector">
</params>

If marking the parameter as optional='true' does not indicate that it can be omitted, then what DOES it mean?

[Isomorphic]

Parameters marked optional can be completely omitted, like a different method signature in Java. For example, if the last parameter of a 3-argument method is optional, you can call it with two arguments.

Parameters where the word optional happens to appear in the description can generally be null. We don't plan on adding a formal notion of this lesser kind of optionality to the docs. Note that it definitely would not be correct to enforce that parameters must be non-null if the word "optional" doesn't occur in the description; lots of parameters may be passed as null and something reasonable happens, but the word "optional" isn't used to describe the behavior that results.

[kylemwhite]

Re: dateTimeFormatter
Sure enough, it doesn't exist. I don't know why I thought it did. I'm guessing I had some bad JavaScript that set that property (improperly) but actually created it. Fortunately TS is helping me fix all my bad habits.

Re: Getter Methods
The old rule identified a getter method of someProperty as a method that is the combination of get and SomeProperty (i.e. getSomeProperty). I've changed it so the rule now looks for a method with that name AND has no parameters. I've also implemented the 3 rules for getter methods so this number has gone down from 42 to 15, and many of those are just different spellings (int/Integer) and different versions of string types (HTML/HTMLString).

Re: Setter Methods
I've implemented the rule that allows the setter type to be a superset of the attribute type. The count has gone down from 88 to 83. Again, many are just different spellings of the same thing or different version of string.

Re: non-optional parameters with 'optional' in the description

Optional here just means you can omit a value for the parameter (pass null or undefined)

If you can omit the value completely, isn't that what optional='true' means? If you're supposed to pass null or undefined, then can we change the type to include " | null"?

Let's look at Date.toNormalDate() for example. I believe this is valid (I've tested and it works):

strDate = myDate.toNormalDate();   // no parameter specified, the default "toLocaleString" will be used (unless it was changed with setNormalDisplayFormat())

But if the parameter is not marked optional='true', Then this will be invalid in TypeScript as it will expect a parameter.

[Blama]

Hi kylemwhite,

Hello kylemwhite, I'm not a TypeScript expert, but I've just tried to use your work in Intellij IDEA, and it seems to work properly.
Kudos for your work!

a big thank you from me as well. Even though I'm not using SmartClient but SmartGWT, I think removing that the small irregularities you find will make the framework as whole better.
Besides of this all SmartClient users will be able to program faster and with less errors with your "TypeScript-Intellisense".

Best regards
Blama

[claudiobosticco]

Hello kylemwhite, I'm not a TypeScript expert, but I've just tried to use your work in Intellij IDEA, and it seems to work properly.
Kudos for your work!

[Isomorphic]

There are 3 cases where your script is flagging a mismatch between a getter and an attribute, where the detected "getter" actually has params, so should not be detected as a getter:

1. method:Calendar.getWorkdayEnd, attrType='Time', return Type = 'String'
2. method:Calendar.getWorkdayStart, attrType='Time', return Type = 'String'
31. method:ListGrid.getSelection, attrType='Selection', return Type = 'Array of ListGridRecord'

Other than these and the other cases we explained above where the type isn't really a mismatch, we can correct everything else you found.

[Isomorphic]

A couple of items from Errors.txt:

Setter Methods with paramter type that does not match the attribute type: 88
1. method:AdaptiveMenu.setItems, attrType='Array of MenuItem', setter Type = 'Array of MenuItem | MenuItem'

Where the setter offers a superset of the types of the attribute, this is not an error. It's just a setter than provides extra flexibility.

Methods with non-optional params with the word 'optional' in the description: 19. Parameters listed here (may be more than one parameter per method)

None of these are errors. Optional here just means you can omit a value for the parameter (pass null or undefined). We've never seen anyone confused by this use of "optional", so don't plan to change it.

Getter Methods with return type that does not match the attribute type: 42

Some of these are not errors:
1. It's not an error for the getter to be a subset of the attribute type (getters cannot return multiple types after all)
2. It's not an error for an attribute of type "Something Properties" to have a getter than returns a "Something"
3. It's not an error for an attribute of type "AutoChild Something" to have a getter that returns a "Something" (same with "MultiAutoChild Something")

Many of the rest actually represent errors and are being assigned, but again it'll take a while to clear these errors out since we're on the verge of putting out a new release.