[Isomorphic]

Look like you've hit a few of the instances where the SmartGWT Java API is hand-coded rather than generated, so the reference docs for those properties weren't corrected to be a machine-readable description of the type (that explains ListGridField.includeInRecordSummaryFields, DataSourceField.filterEditorType, and LayoutProperties.placeHolderProperties). We'll get these three fixed - please keep letting us know about any of these as they can be quickly fixed.

As far as "or" vs "|", and the 3 array notations - yes, our own tools are tolerant of these minor variations. We'll get this cleaned up, standardizing on "|" and the "Array of " wording, but to be able to proceed we'd recommend just having your script deal with these variations (which should be easy).

Note we won't be going with your suggestion of separate valueType tags as that becomes quite verbose for things like parameters, and it usually doesn't make sense to have completely different descriptions for each possible argument type.

[kylemwhite]

Yes, I am already working around the inconsistencies and that will work for now. If, however, we want to maintain an up-to-date typedef file(s) as new versions are released, then we'd want that to be auto-generated and not have to implement new workarounds. Which brings up another idea. Can we get some kind of version number in the referenceDocs file? Maybe in a top-level root tag or something. Currently I am modifying the file to add a root tag anyway (because the .NET parser wants one) but it would be nice to have some global info like the version number, build date etc which would then end up in the typedef files as well.

[Isomorphic]

We haven't proposed keeping anything in your script that would need to be revisited when new versions of SmartClient are released.

Adding version information to referenceDocs.xml makes sense, we'll try to get that done soon. For now, you could pull this information from either the .zip download filename or from docs/readme.html.

[kylemwhite]

More weirdness: Some classes which inherit from other clasess implement the (seemingly) same property but with a different type. For example: TabSet has a skinImgDir property of type string but it inherits from Canvas which has a skinImgDir property of type URL. Of course they're both really strings by why would a sublass redefine a property? I see that the TabSet version has a default value. Is that why?

Similarly, DynamicForm redefines valuesManager (as ValuesManger | global id) from Canvas (which is just ValuesManager) but neither has a default value. Are these on purpose?

[kylemwhite]

BaseWidget missing inheritsFrom Class?

[Isomorphic]

Right, it's common in OOP systems to re-doc a property on a subclass to explain different behavior, different default value, etc.

All of the types declared for SCImgDir are just strings, but we'll clean this up so they all say SCImgURL.

Similarly, the valuesManager property does allow either a ValuesManager or (String) ID of a valuesManager, we'll make that consistent as well.

BaseWidget was recently introduced to explain some drag-and-drop properties that are in common between Canvas and DrawItem, and so missed out on the @inheritsFrom docs we added everywhere - we'll get that one corrected too.

[kylemwhite]

I'm making good progress. I am almost to the point where everything works for my project (subset of classes/objects and subset of methods). There are, of course, lots of issues with the referenceDocs.xml file, too many to list in the forum here so part of my program will now try to identify the issues and generate a report so that we may easily keep track of them. I have a few fundamental questions though:

1. How is an object (called plain old javascript object in the docs) different than a class? At first I thought it might be that an object doesn't inherit from anything or have methods but I've found examples that violate those rules. So what is the rule that makes an object an object vs. a class? If I know the rule, then I can easily validate the file. It doesn't really matter to the TypeScript definition library, everything is an interface anyway, but I'm curious and if you've decided to call them different things, then there must be a reason.

2. I'm using the I flag to create 'Properties' interfaces. These represent classes (or objects?) that can be created and type-checked inside a call to .create(). For example, if you type

isc.TabSet.create({

intellisense will give you all of the possible properties that can be passed into the TabSet.create() method but not the ones that can't (i.e. only the properties marked with 'I'). This has already helped my identify stuff I was passing in that wouldn't be used anyway or was misspelled etc. In my old JavsScript code, I am also passing method definitions this way and it works. But out of 3,063 defined methods, only 6 are marked with the I flag, which makes me think that the I flag isn't really accurate for methods. So, is the I flag valid on methods or can I define any method in the call to create()?

[Isomorphic]

As before, generalities don't really help but specific instances will.

1. As the docs say, Object means a plain JavaScript Object. As with JavaScript in general, an Object can have methods added it to it as properties. What specific API(s) are you looking at where it's unclear what to generate for TypeScript?

2. methods can't have IRWA flags at all (there is not even a way to declare such a thing in our JS doc format), so what specific methods do you think have an "I" flag? Yes, method overrides and custom methods can be passed to create(), there is no need for a special flag to allow this

[kylemwhite]

As before, generalities don't really help but specific instances will.

1. As the docs say, Object means a plain JavaScript Object. As with JavaScript in general, an Object can have methods added it to it as properties. What specific API(s) are you looking at where it's unclear what to generate for TypeScript?

As I mentioned, it doesn't really matter to TypeScript, they will all be called interfaces anyway. I was just curious as to the Isomorphic definition of object vs. class. POJO doesn't really explain it. Objects have inheritence (AdvancedCriteria inherits from Criterion for example), they have methods etc. Why are they called something different? It seems to me they are the same thing as a class. I'm just trying to understand the documentation.

2. methods can't have IRWA flags at all (there is not even a way to declare such a thing in our JS doc format), so what specific methods do you think have an "I" flag? Yes, method overrides and custom methods can be passed to create(), there is no need for a special flag to allow this

Methods with the I in the flags attribute: DataSource.convertRelativeDates, DataSourceField.exportForceText, FacetChart.getMinClusterSize, FormItem.hide, FormItem.redraw, FormItem.showMethods.

I see now that sometimes there's other stuff in the flags attribute (which just happen to contain I) I'm not sure what these mean. But, if all method overrides can be passed to the create() method, that's great, I'll just include them all in the Properties objects. Here's the code from the xml file.

<docItem ref="method:DataSource.convertRelativeDates" type="method" definingClass="class:DataSource" description=" Takes all relative date values found anywhere within a Criteria / AdvancedCriteria object&amp;#010 and converts them to concrete date values, returning the new criteria object.&amp;#010" [B]flags="Criteria : null : IRW"[/B] name="convertRelativeDates">

<docItem ref="method:DataSourceField.exportForceText" type="method" definingClass="class:DataSourceField" description=" When using ${isc.DocUtils.linkForRef('method:DataSource.recordsAsText')}, what approach (if any) should be used to force&amp;#010 values to be intepreted as text instead of heuristically parsed as dates, times or other&amp;#010 structured types.&amp;#010" [B]flags="ForceTextApproach : null : IR"[/B] name="exportForceText">
</docItem>

<docItem ref="method:FacetChart.getMinClusterSize" type="method" definingClass="class:FacetChart" description=" Returns the minimum cluster size (for clustered charts), or minimum bar thickness (for &amp;#010 histogram or stacked charts) for the specified ${isc.DocUtils.linkForRef('method:FacetChart.getDataLabelFacet','data label\n facet')} value.  Only applicable to a column, bar, or histogram chart.  No default&amp;#010 implementation.  Both this minimum and ${isc.DocUtils.linkForRef('attr:FacetChart.minBarThickness')} are used together to&amp;#010 determine the effective minimum of the cluster or bar stack.&amp;#010 &lt;P&gt;&amp;#010 Per-facet-value minimum cluster sizes aren't supported for &amp;#010 ${isc.DocUtils.linkForRef('object:MetricSettings','multi-axis')} charts, in which multiple chart types are overlaid onto&amp;#010 the same chart.&amp;#010 &amp;#010 &lt;P&gt;&amp;#010 Note that this method is simply an override point, since it has no default&amp;#010 implementation.&amp;#010 &amp;#010&amp;#010" [B]flags="facetValueId"[/B] name="getMinClusterSize">

<docItem ref="method:FormItem.hide" type="method" definingClass="class:FormItem" description=" Hide this form item.&amp;#010 &lt;BR&gt;&lt;BR&gt;&amp;#010 This will cause the form to redraw.  If this item had an item.showIf expression, it will&amp;#010 be destroyed.&amp;#010" [B]flags="I"[/B] name="hide">
</docItem>

<docItem ref="method:FormItem.redraw" type="method" definingClass="class:FormItem" description=" Redraw this form item.&amp;#010 &lt;p&gt;&amp;#010 Depending on the item and the ${isc.DocUtils.linkForRef('attr:FormItem.containerWidget')} it's embedded in, this may redraw&amp;#010 this particular item or require a redraw of all items in the form.&amp;#010 &lt;p&gt;&amp;#010 Do not call this method unless the documentation directs you to do so.  Calling&amp;#010 &lt;code&gt;redraw()&lt;/code&gt; unnecessarily has significant performance consequences.&amp;#010&amp;#010" [B]flags="I"[/B] name="redraw">

<docItem ref="method:FormItem.show" type="method" definingClass="class:FormItem" description=" Show this form item.&amp;#010 &lt;p&gt;&amp;#010 This will cause the form to redraw.  If this item had an item.showIf expression, it will&amp;#010 be destroyed.&amp;#010" [B]flags="I"[/B] name="show">
</docItem>

[Isomorphic]

1. because, as the documentation states, you create Objects via "new Object()" or JS object literal syntax ({ ... }), whereas instances of anything that inherits from Class are created via isc.ClassName.create(). The inheritance of one Object from the other has the usual meaning: properties from the superclass are valid on instances of the subclass.

2. flags on methods don't mean anything, ignore them. Our JS doc parser was accepting a couple of garbled method declarations without flagging them as errors, hence the flags. We'll get rid of those.

As far as what the flags mean for *properties*, that's explained here; everywhere you see the shorthand IRWA flags, it's a link to this discussion.

[kylemwhite]

Ok, I think I got it: classes ultimately inherit from Class. Objects do not. Thanks. This helps with the generator as I now know to check the inheritance chain for all classes but not for objects.

I will ignore the flags on methods.

I am currently only looking at the I flag for properties to create (what I call) the Properties Objects. These will aid the developer when calling the create() method. I may eventually utilize the R and W flags if it seems like it will be useful (like making properties read only).

[kylemwhite]

Oh, and what's the 'A' for in IRWA?

[Isomorphic]

So if we read you correctly: you are creating two TypeScript interfaces per class:

1. one named ClassNameProperties which contains all "I" properties and all methods, is the sole argument to ClassName.create() and can be passed into methods that declare a "ClassName Properties" argument
2. one named ClassName which contains all R or W properties, and again all methods, and is what is returned by create() and expected wherever an an argument type is ClassName

If so, this is correct.

The 'A' means Advanced - a clue to developers that if they are looking at that API they must either be doing something complicated or they've missed a simpler approach. We'll update the "flags" doc to cover this.

[kylemwhite]

1. one named ClassNameProperties which contains all "I" properties and all methods, is the sole argument to ClassName.create() and can be passed into methods that declare a "ClassName Properties" argument

Correct.

2. one named ClassName which contains all R or W properties, and again all methods, and is what is returned by create() and expected wherever an an argument type is ClassName

Correct.

And one more named ClassNameStatic which contains all the Class methods and properties.

[kylemwhite]

New version posted, it's not everything but it works.

https://github.com/kylemwhite/isc

Feedback is welcome.