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

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.

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

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]

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]

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?

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

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

Also from Errors.txt: KeyIdentifier has a declaration as an Object with properties, so it shouldn't be in your list of suspected string types. But we'll take care of the rest of these.

[kylemwhite]

1. Re: ListGrid.selection
Can it be defined as Selection | CellSelection? Sounds like that would be more accurate and compatible with TypeScript.

2. Re: ToolStripButton
Ok, nothing for me to do here. The xml file says Button which correct most of the time.

3. Re: isc.addProperties
Understood that it can take multiple arguments and the generator can handle that. My point was that the usual way that is described is by putting arguments 0-N in the name field, but in this one case, it's in the type field and the name field contains a single bracket. I'm assuming this is a typo.

4. Re: SectionStackSection.addItem()
Well that makes sense then as my first experience with SmartClient was really SmartGWT and I probably copied some code into my current JavaScript (now TypeScript) project. Why not spread the love and let us JS/TS people see it too? Sometimes you want to add something to a SectionStackSection after it's already been initialized. We can do that, right?

5. Re: Classes missing inheritsFrom
If they inherit from Class, then why not specify that? I don't see how it's redundant if it's not specified anywhere else (or is it?) I could assume that any class without an inheritsFrom attribute really inherits from Class except that...
If they are just objects, then can you change the type field to object (type="object" instead of type="class")? I need some way to know if an entity is supposed to inherit from Class or not.

6. Re: "Should string type values have quotes or not?"
This is probably best explained with an example. Some string-type values (or string enums or whatever) are defined like this:

<docItem ref="type:ControlName" type="type" description="..." name="ControlName">
<values value=""boldSelection"" description="A button to make the current selection bold."/>
<values value=""italicSelection"" description="A button to make the current selection italic."/>

(note the double double quotes around the value) and some like this:

<docItem ref="type:PointShape" type="type" description="Supported data point shapes for ${isc.DocUtils.linkForRef('attr:FacetChart.pointShapes')} are:" name="PointShape">
<values value="Oval"></values>
<values value="Square"></values>

I think the second type correlates to the Values with a period most of the time (but not in the example above).

7. Re: KeyIdentifier
Well wattya know?, it IS an object. I'll have that generated on the next round.

[kylemwhite]

I see how the KeyIdentifier thing came up. It's from this piece of the file

 <docItem defaultValue="null" type="attr" definingClass="object:MenuItem" ref="attr:MenuItem.keys" 
valueType="KeyIdentifier | Array of [B]KeyIdentifer[/B]" description="Shortcut key(s) to fire the menu item action. Each key can be defined as a ${isc.DocUtils.linkForRef('object:KeyIdentifier')}.&#010 To apply multiple shortcut keys to this item, set this property to an array of such key&#010 identifiers." flags="IR" name="keys">
   <groups>menuKeys</groups>
 
  </docItem>

Notice in the valueType, it is misspelled in Array of KeyIdentifer (missing an i).

[jaredm]

kylemwhite thank you for taking this on. I just came across it and am really looking forward to using it (we use TypeScript for other stuff, for some reason no one thought to apply it to SmartClient)!

[Isomorphic]

1. Re: ListGrid.selection
Can it be defined as Selection | CellSelection? Sounds like that would be more accurate and compatible with TypeScript.

Sure, we can do this.

3. Re: isc.addProperties
Understood that it can take multiple arguments and the generator can handle that. My point was that the usual way that is described is by putting arguments 0-N in the name field, but in this one case, it's in the type field and the name field contains a single bracket. I'm assuming this is a typo.

Ah OK, we thought you meant that functions with N arguments couldn't be handled in general. Since they can, we've just corrected the typo that made this parse incorrectly. So it should now say "arguments 1-N" in analogy with other such methods (in tomorrow's builds).

4. Re: SectionStackSection.addItem()
Well that makes sense then as my first experience with SmartClient was really SmartGWT and I probably copied some code into my current JavaScript (now TypeScript) project. Why not spread the love and let us JS/TS people see it too? Sometimes you want to add something to a SectionStackSection after it's already been initialized. We can do that, right?

It's just a plain JavaScript Object, so we don't have a way to place methods on those. This is different in SmartGWT, where even plain JavaScript Objects like this end up with Java classes wrapping them. Note that the SmartClient way to add an item after init is sectionStack.addItem().

5. Re: Classes missing inheritsFrom
If they inherit from Class, then why not specify that? I don't see how it's redundant if it's not specified anywhere else (or is it?) I could assume that any class without an inheritsFrom attribute really inherits from Class except that...
If they are just objects, then can you change the type field to object (type="object" instead of type="class")? I need some way to know if an entity is supposed to inherit from Class or not.

If it's type="class" it inherits from Class if nothing else is specified. If it's type="object" it doesn't inherit from anything (or, if it's what TypeScript wants, you can say that it inherits from the native JavaScript Object).

6. Re: "Should string type values have quotes or not?"
This is probably best explained with an example. Some string-type values (or string enums or whatever) are defined like this:

<docItem ref="type:ControlName" type="type" description="..." name="ControlName">
<values value=""boldSelection"" description="A button to make the current selection bold."/>
<values value=""italicSelection"" description="A button to make the current selection italic."/>

(note the double double quotes around the value) and some like this:

<docItem ref="type:PointShape" type="type" description="Supported data point shapes for ${isc.DocUtils.linkForRef('attr:FacetChart.pointShapes')} are:" name="PointShape">
<values value="Oval"></values>
<values value="Square"></values>

I think the second type correlates to the Values with a period most of the time (but not in the example above).

Thanks for the example, we'll look into what's causing this.

[Isomorphic]

Actually, on #6, here's how to handle it:

1. if there are quotes, that's the literal string value
2. if there aren't, it's a reference to another property, eg TableView.NAVICON_ONLY means go look up the class attribute NAVICON_ONLY on TableView, and use that attribute's value. That particular attribute was missing from the docs, but we're adding it, and also doing a review of any others that might be missing that are referred to by type declarations.

[kylemwhite]

If it's type="class" it inherits from Class if nothing else is specified.

Unless, of course, it is Class or isc. If the classes specified inheritsFrom='Class', then they would be easily distinguished from classes that are just missing the attribute such as:

• Layout
• VLayout
• HLayout
• ToolStripButton
• SectionStack
• ToolStrip
• RestDataSource
• HTMLPane
• Menu
• etc.

I've found 192 classes (not objects) that don't have an inheritsFrom attribute. Ok, I know that Class and isc don't inherit from anything, those are special because they are absolutely base classes. For the other 190, how can the generator tell if they are supposed to inherit from Class or if they are just missing a legit inheritsFrom attribute?

If it's type="object" it doesn't inherit from anything

Well, according to the file, that's not true. There are 8 objects with inheritFrom attributes:

1. AdvancedCriteria inheritsFrom Criterion
2. EditNode inheritsFrom PaletteNode
3. LinearGradient inheritsFrom Gradient
4. ListGridRecord inheritsFrom Record
5. MenuItem inheritsFrom ListGridRecord
6. NavItem inheritsFrom TreeNode
7. RadialGradient inheritsFrom Gradient
8. SimpleGradient inheritsFrom Gradient

or.... are they supposed to be classes?