[Isomorphic]

Looking over your Errors.txt..

About the set of classes missing inheritsFrom, most of these either inherit from Class or are just Objects. We don't plan to add the (redundant) declaration here, so please just make that part of the logic of the script. We'll fix the ones that don't fall into those two cases.

What does this mean:

==== Should string type values have quotes or not? ====
	Contrained String Type Values with quotes: 216
	Contrained String Type Values without quotes: 657

Are you talking about default values or something?

[Isomorphic]

Here's a couple issues that won't be caught by the code generator but that I've discovered since using TypeScript:

1. In the Grid to Excel showcase example, there's a line of code:

var selection = countryList.selection.getSelectedCells() || [];

The "selection" property is a CellSelection when canSelectCells is enabled. So a more correct way to write that code would be countryList.getCellSelection().getSelectedCells(), we'll fix that for clarity.

2. According to the docs, ToolStripButton inherits from Button but in the description it says:


So, does a ToolStripButton inherit from Button or StretchImgButton?

It actually depends on your skin. It's a Button unless you use an older skin. We'll fix the description to reflect the more common case that it's a Button.

isc.addProperties: this method can take N arguments. For simplicity we will update the docs to show 3 optional args but just add a description saying that actually you can pass as many as you like.

SectionStackSection.addItem(): this was just an extra API for SmartGWT to make Java people feel more comfortable. Also the code ends up less verbose in Java. In JavaScript you just provide an Array of items. So nothing to do here.

[kylemwhite]

SectionStackSection: in GWT there is a method addItem(Canvas) defined and I think it exists in SmartClient as well but it's not in the docs. Is is supposed to be?

[kylemwhite]

Looks like there's a typo for the multiple arguments parameter in classMethod:isc.addProperties. The name='[' and type='arguments 1-N'

 <docItem ref="classMethod:isc.addProperties" type="classMethod" definingClass="class:isc" description="..." flags="" name="addProperties">
   <seeAlso ref="classMethod:Class.addProperties"></seeAlso>
  <seeAlso ref="method:Class.addProperties"></seeAlso>
  <params optional="false" type="object" description="object to add properties to" name="destination"></params>
  <params optional="false" type="[I][B]arguments 1-N[/B][/I]" description="[B][I]] [/I][/B](object) objects to obtain properties from.
Properties of all arguments other than destination are applied in turn." [I][B]name="["[/B][/I]></params>
  <returns type="object" description="returns the destination object"/>
 
  </docItem>

For multiple arguments, usually the name is 'arguments 0-N' and the type is a regular type as usual.

[kylemwhite]

Here's a couple issues that won't be caught by the code generator but that I've discovered since using TypeScript:

1. In the Grid to Excel showcase example, there's a line of code:

var selection = countryList.selection.getSelectedCells() || [];

countryList.selection returns a Selection but, according to the docs, Selection does not have a getSelectedCells() method. Is it missing from the docs?

2. According to the docs, ToolStripButton inherits from Button but in the description it says:

Simple subclass of StretchImgButton

So, does a ToolStripButton inherit from Button or StretchImgButton?

[kylemwhite]

New version generated with snapshot 5-1-2017. Now extracting the SmartClient version from group:browserSupport.description. Enhanced the Errors.txt file to more easily communicate issues with the referenceDocs.xml file. As these get cleaned up, I'll put in more tests for method parameters.

[kylemwhite]

Nice!

Thanks. It has already helped me refactor and debug my application.

Is the script itself available somewhere?

Well, the 'script' is a C# console program and it's really ugly right now. I've been focused on just getting the output to a state that works, has good documentation and makes it as easy as possible for a developer (like me) to use the SmartClient library. Eventually I'd like to post it as well but it's not ready for prime time now.

Did you have any other issues where we can adjust the docs to avoid workarounds in the generator script? We already put in the @baseType annotation, fixed those IRW flags on methods, and we're in the process of fixing some of the others (like the dynamicForm.valuesManager type declaration).

In the repository, there is an errors.txt file that lists issues I've found. Note that it was generated using an older version of the referenceDocs file (4/18/2017 I think). Having a version in the docs would be good so that the library and error file will point out which version they were generated from. One thing that would be easy to fix (if it hasn't been done already) is the inheritsAttribute. The errors.txt file lists all the classes that don't inherit anything.

Next week, I'll download the latest, re-generate and hopefully take out some of the string-type hacks by using the new baseType attribute.

[Isomorphic]

Nice!

Is the script itself available somewhere?

Did you have any other issues where we can adjust the docs to avoid workarounds in the generator script? We already put in the @baseType annotation, fixed those IRW flags on methods, and we're in the process of fixing some of the others (like the dynamicForm.valuesManager type declaration).

[kylemwhite]

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

https://github.com/kylemwhite/isc

Feedback is welcome.

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

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

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

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

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

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>