docs: extract out common types #11391

sgtcoolguy · 2019-12-12T16:05:27Z

JIRA
https://jira.appcelerator.org/browse/TIMOB-27688

Description:

Updates to titanium-docgen 4.1.0 which now warns about using generic Dictionary/Object types
Extracted out Size type: width and height
Extracted Dimension type from View's yml file, have it extend Size and add x and y properties
- Ti.Blob.#imagesAsCropped() now refers to Dimension rather than a custom type that had the same properties.
- Ti.Media CameraMediaItemType now refers to Dimension for cropRect and Size for previewRect rather the defining custom types with same properties.
Extracted Padding type from ViewPadding. Attempted to clean up any special types that had the same concept (basically any padding/inset properties/types) to refer to it.
- Kept TabIconInsets, had it extend Padding and noted right/bottom are excluded.
- Kept TextFieldPadding, had it extend Padding and noted top/bottom are Android-only.
Fix Ti.DB.ResultSet #field() and #fieldByName() returns to be a single entry with type as an array of possible return types.

sgtcoolguy · 2019-12-12T16:05:52Z

cc @drauggres You might be interested in these changes

build · 2019-12-12T16:07:26Z

	Fails
🚫	Tests have failed, see below for more information.

	Messages
📖	💾 Here's the generated SDK zipfile.
📖	✊ The commits in this PR match our conventions! Feel free to Rebase and Merge this PR when ready.
📖	❌ 1 tests have failed There are 1 tests failing and 700 skipped out of 7381 total tests.

Tests:

Classname

Name

Time

Error

ios.ipad.Titanium.Blob

#toString() returns "[object TiBlob] for binary content (13.2.2)

0.043

Error: expected undefined to equal '[object TiBlob]'
fail@file:///Users/build/Library/Developer/CoreSimulator/Devices/E6250863-45A7-40F1-9840-23A71FEA8F02/data/Containers/Bundle/Application/C62950F9-13B8-4BFF-857C-544ED8C4475D/mocha.app/node_modules/should/cjs/should.js:275:19
value@file:///Users/build/Library/Developer/CoreSimulator/Devices/E6250863-45A7-40F1-9840-23A71FEA8F02/data/Containers/Bundle/Application/C62950F9-13B8-4BFF-857C-544ED8C4475D/mocha.app/node_modules/should/cjs/should.js:356:13
file:///Users/build/Library/Developer/CoreSimulator/Devices/E6250863-45A7-40F1-9840-23A71FEA8F02/data/Containers/Bundle/Application/C62950F9-13B8-4BFF-857C-544ED8C4475D/mocha.app/ti.blob.test.js:386:28
file:///Users/build/Library/Developer/CoreSimulator/Devices/E6250863-45A7-40F1-9840-23A71FEA8F02/data/Containers/Bundle/Application/C62950F9-13B8-4BFF-857C-544ED8C4475D/mocha.app/ti-mocha.js:6535:54167
file:///Users/build/Library/Developer/CoreSimulator/Devices/E6250863-45A7-40F1-9840-23A71FEA8F02/data/Containers/Bundle/Application/C62950F9-13B8-4BFF-857C-544ED8C4475D/mocha.app/ti-mocha.js:6535:58607
file:///Users/build/Library/Developer/CoreSimulator/Devices/E6250863-45A7-40F1-9840-23A71FEA8F02/data/Containers/Bundle/Application/C62950F9-13B8-4BFF-857C-544ED8C4475D/mocha.app/ti-mocha.js:6535:59452
next@file:///Users/build/Library/Developer/CoreSimulator/Devices/E6250863-45A7-40F1-9840-23A71FEA8F02/data/Containers/Bundle/Application/C62950F9-13B8-4BFF-857C-544ED8C4475D/mocha.app/ti-mocha.js:6535:58015
file:///Users/build/Library/Developer/CoreSimulator/Devices/E6250863-45A7-40F1-9840-23A71FEA8F02/data/Containers/Bundle/Application/C62950F9-13B8-4BFF-857C-544ED8C4475D/mocha.app/ti-mocha.js:6535:57979
next@file:///Users/build/Library/Developer/CoreSimulator/Devices/E6250863-45A7-40F1-9840-23A71FEA8F02/data/Containers/Bundle/Application/C62950F9-13B8-4BFF-857C-544ED8C4475D/mocha.app/ti-mocha.js:6535:57667
file:///Users/build/Library/Developer/CoreSimulator/Devices/E6250863-45A7-40F1-9840-23A71FEA8F02/data/Containers/Bundle/Application/C62950F9-13B8-4BFF-857C-544ED8C4475D/mocha.app/ti-mocha.js:6535:57763
timeslice@file:///Users/build/Library/Developer/CoreSimulator/Devices/E6250863-45A7-40F1-9840-23A71FEA8F02/data/Containers/Bundle/Application/C62950F9-13B8-4BFF-857C-544ED8C4475D/mocha.app/ti-mocha.js:5764:23

Dependencies with modified semantic versioning:

titanium-docgen - from ^4.0.0 to ^4.1.0

Generated by 🚫 dangerJS against f300479

sgtcoolguy · 2019-12-16T15:40:12Z

Relates to #11386

@janvennemann Perhaps you'd be best for review? I attempted to try and basically "refactor" our docs to use some commonly defined types for many of the "simple object which has a few properties" arguments/callbacks. The goal was to clean the docs, try and re-use common types when defining them, and hopefully to improve TypeScript definitions and IDE content assist indirectly.

apidoc/Titanium/UI/2DMatrix.yml

drauggres · 2019-12-16T16:42:30Z

apidoc/Titanium/UI/ScrollView.yml

-        type: zoomScaleOption
+      - name: options
+        summary: A JS object with an `animated` property which determines whether the scrollable region reposition should be animated
+        type: AnimatedOptions


zoomScaleOption was iOS-only

that's true, but this method is iOS-only so the method and any arguments are therefore iOS-only.

drauggres · 2019-12-16T16:42:49Z

apidoc/Titanium/UI/ScrollView.yml

-        summary: Determines whether the scrollable region reposition should be animated
-        type: contentOffsetOption
+        summary: A JS object with an `animated` property which determines whether the scrollable region reposition should be animated
+        type: AnimatedOptions


contentOffsetOption was iOS-only

that's true, but this method is iOS-only so the method and any arguments are therefore iOS-only.

drauggres · 2019-12-16T16:58:37Z

apidoc/Titanium/UI/Window.yml

@@ -1147,7 +1149,7 @@ properties:
    description: |
        This was separated from the <Titanium.UI.Window.androidback> event. You need to define this
        callback if you explicitly want to override the back button behavior.
-    type: Callback<Object>
+    type: Callback<void>


Is this the correct way to define callback with no arguments? I can't find any other Callback<void> (except one in validate.js from titanium-docgen).

yeah I believe it is in our doc format. Callback is synonymous with Function. As to the void arg, well that is seen as ok in the validation. Otherwise, I'm not sure how to define that the function takes no arguments. I think the generators are ok with with void arg

drauggres · 2019-12-16T17:00:02Z

apidoc/Titanium/UI/iOS/MenuPopup.yml

-        summary: Includes options how the menu popup should be hidden.
-        type: MenuPopupHideParams
+        summary: Includes options how the menu popup should be hidden. Introduced in SDK 5.2.0
+        type: AnimatedOptions


Default was {animated: true}

Yeah, I struggled with how to handle the cases where the default animated value is true vs false. Do we just mention it in the summary? Do I define a new sub-type of AnimatedOptions that just overrides the property's default value to be true?

To do some follow-up: These special "types" I've been extracting are really a better match as TypeScript interfaces, not classes. Because there's no actual way to instantiate an AnimatedOptions type - no such thing exists. It's more about the shape of a generic JS object we expect to be passed in to the methods. As such, the conversion to TypeScript would drop any "default" values on objects like this. It's more about documenting the property names, whether they're optional/required, and if they're "readonly". So trying to set the default value on the type may actually be moot - and I may need to just be thorough in mentioning the assumed defaults on all the methods that accept it. 😢

Just thought of another possible way to document this - set the default value on the method argument to the raw JS object that it "assumes". Old docs already do this for things like Point (i.e. { x: 0, y: 0 }) We've been pretty loosey-goosey with how we handle default though. Not sure if we'd need more rules around it or just assume that the string value is the raw JS code/value that is assumed to be default. (How would we validate that, since I know we do have cases where we have sentences there?)

At least we should keep this information in summary or description (same for iOS-only properties).

drauggres · 2019-12-16T17:02:39Z

apidoc/Titanium/UI/iPad/Popover.yml

@@ -39,14 +39,14 @@ methods:
    parameters:
      - name: options
        summary: Display properties to use when hiding the popover.
-        type: PopoverParams
+        type: AnimatedOptions


Default was {animated: true}

same as above

drauggres · 2019-12-16T17:02:50Z

apidoc/Titanium/UI/iPad/Popover.yml


  - name: show
    summary: Displays the popover.
    parameters:
      - name: params
        summary: Display properties to use when displaying the popover.
-        type: PopoverParams
+        type: ShowPopoverParams


Default was {animated: true}

janvennemann

Only two minor notes, the rest looks good.

PS: Man this looks like some tedious work, awesome job!

apidoc/Titanium/UI/Padding.yml

apidoc/Titanium/UI/View.yml

drauggres · 2019-12-17T09:11:42Z

apidoc/Titanium/Platform/Platform.yml

+    optional: true
+
+  - name: UIApplicationOpenURLOptionsAnnotationKey
+    type: Array


Here must be a type of items stored in the array.

Yeah... I couldn't find what the heck goes in here.

FYI: with type: Array current version of the "typescript" generator will produce incorrect output.

sgtcoolguy added the docs label Dec 12, 2019

build added this to the 9.0.0 milestone Dec 12, 2019

build requested a review from a team December 12, 2019 16:07

build added the needs jira 🚨 label Dec 12, 2019

sgtcoolguy force-pushed the titanium-docgen-4.1.0 branch from 7f96ae8 to f906edd Compare December 12, 2019 16:13

sgtcoolguy marked this pull request as ready for review December 16, 2019 15:38

sgtcoolguy mentioned this pull request Dec 16, 2019

docs: fix mistakes in apidocs #11393

Merged

drauggres reviewed Dec 16, 2019

View reviewed changes

apidoc/Titanium/UI/2DMatrix.yml Show resolved Hide resolved

sgtcoolguy added 19 commits December 16, 2019 11:10

chore(package): update titanium-docgen to version 4.1.0

dd2759f

chore(package): update lockfile

339eb30

docs(db): fix return type for field/fieldByName

0ce73aa

docs(media): improve property docs for RouteDescription

6b2d503

docs(media): previewImage success callback gets SuccessResponse

a96575f

docs: combine various inset/padding types into Padding

91aa43c

docs: use Dimension and Size types in place of redundant custom types

3309ef4

docs: refer to Size type for shadowDict offset

98b07d4

docs: break out transition animation type

7410199

docs: fix types on window

c60a4d4

docs(label): extract LabelLineSpacing type

f8d14a6

docs(app): refer to Dimension type for keyboardframchanged

5ff4711

docs(file): fix returns for getParent

8b40a59

docs(proxy): refer to Event type for callback argument on event listener

18033e9

docs(listsection): fix returns for getItemAt

49a0fbd

docs(listview): note that item in event may actually be -1 on ios

87d114a

docs(network): add since value in structure, not summary

c07b59d

docs(textfield): left and right button shoudl be views

0bc813a

docs: extract AnimatedOptions that support object w/ animated property

0e04944

sgtcoolguy added 19 commits December 16, 2019 11:10

docs: extract more uses of AnimatedOptions and Point in apis

e55b6e1

docs: extract an AnimatedWithDurationOptions type

3564720

docs: animated defaults to false in most cases, true for window methods

c1ff829

docs(emaildialog): refer to AnimatedOptions

3eac29b

docs(label): refer to Point, not Dictionary for shadowOffset

77e6f27

docs(window): clean up close options, refer to AnimatedOptions

a1bf0c7

docs: refer to Point/Size in place of generic Dictionary

3f138a8

docs: extract horizontal-only variant of Padding

e080ca6

docs(scrollview): use Point/Size not Dictionary

dc24931

docs(platform): extract out open url options

562870c

docs(animation): center is a Point

3738165

docs(clipboard): clean up docs

4786528

docs(platform): fix non-ascii character

829dfc2

docs(clipboard): fix reference to null data type

af96af8

docs(view): extract simple types, fix platforms for event properties

8c26dd7

docs: fix property name for application shortcuts itemtype -> identifier

44660c2

docs: add TODO in NavigationWindow

448363f

docs: add some notes in OptionDialog

6fd9224

docs(matrix2d): fix param name reference, refer to Point

290d45b

sgtcoolguy force-pushed the titanium-docgen-4.1.0 branch from 6a6ef46 to 290d45b Compare December 16, 2019 16:12

drauggres reviewed Dec 16, 2019

View reviewed changes

sgtcoolguy added 2 commits December 16, 2019 13:40

docs: note default value for animated when taking AnimatedOptions

084d8cb

docs: set explicit default for AnimatedOptions args

e79bbb7

janvennemann requested changes Dec 16, 2019

View reviewed changes

apidoc/Titanium/UI/Padding.yml Outdated Show resolved Hide resolved

apidoc/Titanium/UI/View.yml Outdated Show resolved Hide resolved

drauggres reviewed Dec 17, 2019

View reviewed changes

sgtcoolguy added 2 commits December 17, 2019 09:11

docs: invert HorizontalInsets/Padding relationship

1b4b78e

docs: add DimensionWithAbsolutes for Ti.Ui.View.rect usage

f300479

build removed the needs jira 🚨 label Dec 17, 2019

sgtcoolguy merged commit 5cdbdf0 into tidev:master Dec 17, 2019

sgtcoolguy deleted the titanium-docgen-4.1.0 branch December 17, 2019 16:32

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: extract out common types #11391

docs: extract out common types #11391

sgtcoolguy commented Dec 12, 2019 •

edited

sgtcoolguy commented Dec 12, 2019

build commented Dec 12, 2019 •

edited

sgtcoolguy commented Dec 16, 2019

drauggres Dec 16, 2019

sgtcoolguy Dec 16, 2019

drauggres Dec 16, 2019

sgtcoolguy Dec 16, 2019

drauggres Dec 16, 2019

sgtcoolguy Dec 16, 2019

drauggres Dec 16, 2019

sgtcoolguy Dec 16, 2019

sgtcoolguy Dec 16, 2019

sgtcoolguy Dec 16, 2019

drauggres Dec 16, 2019

drauggres Dec 16, 2019

sgtcoolguy Dec 16, 2019

drauggres Dec 16, 2019

sgtcoolguy Dec 16, 2019

janvennemann left a comment

drauggres Dec 17, 2019

sgtcoolguy Dec 17, 2019

drauggres Dec 17, 2019

docs: extract out common types #11391

docs: extract out common types #11391

Conversation

sgtcoolguy commented Dec 12, 2019 • edited

sgtcoolguy commented Dec 12, 2019

build commented Dec 12, 2019 • edited

Tests:

sgtcoolguy commented Dec 16, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

janvennemann left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sgtcoolguy commented Dec 12, 2019 •

edited

build commented Dec 12, 2019 •

edited