[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]

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.

[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').

[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]

@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.

[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.

[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?

[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!

[kylemwhite]

Isomorphic: Currently, the ClassNameProps interfaces declare every method for the particular class (for overriding). This is probably not ideal as I'm sure there are many (most?) methods that should not be overridden. Is there any way the generator could determine which methods are appropriate to expose in the ClassNameProps interfaces? For example, when creating a new ListGrid, one certainly might want to override (implement) the cellClick() method so it should definitely be exposed in the ListGridProps class. However, it's probably not appropriate to expose the bringToFront() method as that's not really meant to be overridden (I don't think). A first attempt might be to expose only those that are marked as being in the events group but I'm not sure if that's completely accurate. Thoughts?

[Isomorphic]

It's valid to override these other methods, so long as the developer doesn't make assumptions about when and how the method will be called that aren't part of the documented guarantees. So we wouldn't want to either prevent this or warn in any way that the property doesn't exist or flag it as a custom property.

[kylemwhite]

Ok, I'll leave it as is... override away!

[Isomorphic]

We've added explicit "inheritsFrom" markings for almost everything now (except, as discussed before, those that extend the base Class), and the last few should be done this week. One note on this: CanvasItem was listed as missing an inheritsFrom in your Errors.txt, but it in fact already had one, so that may be some kind of glitch in the script.

[kylemwhite]

Yes, I noticed that a lot of them have been fixed, thanks. I'm looking at the latest file (http://www.smartclient.com/smartclie...erenceDocs.xml) and I don't see the inheritsFrom attribute on CanvasItem

 <docItem type="class" ref="class:CanvasItem" description="FormItem which renders a Canvas inline in a DynamicForm instance.&#010 <P>&#010 CanvasItem is ${isc.DocUtils.linkForRef('attr:CanvasItem.shouldSaveValue','shouldSaveValue')}:false by default, meaning that&#010 no value from the CanvasItem will be present in ${isc.DocUtils.linkForRef('method:DynamicForm.getValues')} and no value will be&#010 saved when ${isc.DocUtils.linkForRef('method:DynamicForm.saveData')} is called. This is appropriate if the Canvas does&#010 not participate in editing a value of the form and is embedded in the form for layout or UI&#010 purposes only (e.g. ${isc.DocUtils.linkForRef('class:ButtonItem')}, ${isc.DocUtils.linkForRef('class:SectionItem')}). Note that some built-in CanvasItem&#010 types override the shouldSaveValue default to true (e.g. ${isc.DocUtils.linkForRef('class:MultiComboBoxItem')}, ${isc.DocUtils.linkForRef('class:RichTextItem')}).&#010 <P>&#010 If you set ${isc.DocUtils.linkForRef('attr:FormItem.shouldSaveValue','shouldSaveValue')}:true, a &#010 ${isc.DocUtils.linkForRef('method:CanvasItem.showValue','showValue')} event will be raised to provide a value that your&#010 item should display. Handle this event by calling methods on the Canvas you've created&#010 to cause the value to be displayed.&#010 <P>&#010 The ${isc.DocUtils.linkForRef('method:CanvasItem.showValue','showValue')} event will be triggered in various situations where&#010 the form receives data, including a call to ${isc.DocUtils.linkForRef('method:DynamicForm.setValues')},&#010 ${isc.DocUtils.linkForRef('method:DynamicForm.editRecord')}, or if ${isc.DocUtils.linkForRef('method:DynamicForm.fetchData')} is called and a Record&#010 is returned. Bear in mind that the <code>showValue</code> event can be called when the form&#010 and your item have not yet been drawn; in this case, store the value for later display.&#010 <P>&#010 To provide a value to the form, call ${isc.DocUtils.linkForRef('method:CanvasItem.storeValue')} whenever the user changes&#010 the value in your Canvas. Generally, if storeValue() is called then&#010 ${isc.DocUtils.linkForRef('attr:CanvasItem.shouldSaveValue','shouldSaveValue')} should be overridden to true. Note that&#010 the form <b>will not</b> call getValue() in order to discover your item's value, so there is&#010 no purpose in overriding this method; instead, call storeValue() to proactively inform the&#010 form about changes to the value. This approach is necessary in order to enable change events.&#010 <P>&#010 If you cannot easily detect changes to values in your Canvas, a workaround is to call&#010 <code>storeValue</code> right before the form saves." name="CanvasItem">
   <attrs>attr:CanvasItem.height</attrs>
  <attrs>attr:CanvasItem.multiple</attrs>
  <attrs>attr:CanvasItem.shouldSaveValue</attrs>
  <attrs>attr:CanvasItem.canvas</attrs>
  <attrs>attr:CanvasItem.canvasConstructor</attrs>
  <attrs>attr:CanvasItem.canvasDefaults</attrs>
  <attrs>attr:CanvasItem.canvasProperties</attrs>
  <attrs>attr:CanvasItem.autoDestroy</attrs>
  <attrs>attr:CanvasItem.overflow</attrs>
  <attrs>attr:CanvasItem.minHeight</attrs>
  <attrs>attr:CanvasItem.maxHeight</attrs>
  <attrs>attr:CanvasItem.editCriteriaInInnerForm</attrs>
  <attrs>attr:CanvasItem.applyPromptToCanvas</attrs>
  <attrs>attr:CanvasItem.prompt</attrs>
  <treeLocation>Client Reference/Forms/Form Items</treeLocation>
  <methods>method:CanvasItem.storeValue</methods>
  <methods>method:CanvasItem.updateCanvasTabPosition</methods>
  <methods>method:CanvasItem.setCanvas</methods>
  <methods>method:CanvasItem.canEditChanged</methods>
  <methods>method:CanvasItem.readOnlyDisplayChanged</methods>
  <methods>method:CanvasItem.shouldDisableCanvas</methods>
  <methods>method:CanvasItem.isFocused</methods>
  <methods>method:CanvasItem.hasAdvancedCriteria</methods>
  <methods>method:CanvasItem.canEditCriterion</methods>
  <methods>method:CanvasItem.getCriterion</methods>
  <methods>method:CanvasItem.setCriterion</methods>
  <methods>method:CanvasItem.setPrompt</methods>
  <methods>method:CanvasItem.createCanvas</methods>
  <methods>method:CanvasItem.showValue</methods>
 
  </docItem>

[kylemwhite]

I hate to bring this up again but I'm still confused on the definition of Class vs. Object. Previously I understood that the difference was that a Class ultimately inherits from the base 'Class'. However, I've manually checked a bunch of classes that don't have an inheritsFrom attribute and found that they do not ultimately inherit from Class. So, if they don't inherit from Class, then why are the called classes? I.e. how are they different from Object? Examples:

• Date
• EBay
• FacetValue
• FileLoader
• History
• isc
• SelectionOutline
• ServerObject
• String
• Time
• TooLStripSeparatorEditProxy
• VisualBuilder
• WSRequest

This is not an exhaustive list, just the one's I happened to manually check through the docs and they are noted in the Errors.txt file.

[kylemwhite]

I see in today's build that the ListGrid.getDataSource() method has been documented. This broke my build (in a good way) because it told me that my own definition of getDataSource() was redundant and so I removed it, all good.

However, I've also been using the property .dataSource to retrieve the string ID of the DataSource. Since the generator is following the rules (i.e. not creating the property if a getter exists) there is no longer a .dataSource property. As a workaround, I've done the following:

(grid as any).dataSource

I think the issue stems from the fact that the .dataSource proprety can hold an object or an ID (or both?). Would it make sense to have a getDataSourceID() method as well?