Document the deprecated ifMessagePort.setPort() method. (#1210)

* Document the deprecated `ifMessagePort.setPort()` method.

* Move to rourltransfer object

* Pass through deprecated flag

* Fix lint issues

.gitignore

@@ -14,4 +14,5 @@ graph.svg
 benchmarks/*.brs
 isolate-*
 v8*.log
-*.cpuprofile
+*.cpuprofile
+.cache.json

scripts/scrape-roku-docs.ts

@@ -1180,13 +1180,32 @@ class Runner {
                 }
             },
             components: {
+                rourltransfer: {
+                    methods: [{
+                        description: 'DEPRECATED: use `.SetMessagePort()` instead. \n\nSets the roMessagePort to be used to receive events',
+                        isDeprecated: true,
+                        deprecatedDescription: 'Use .SetMessagePort instead. Some legacy objects still implement the older `SetPort` function, but apps should not be using it.',
+                        name: 'SetPort',
+                        params: [
+                            {
+                                'default': null,
+                                'description': 'The port to be used to receive events.',
+                                'isRequired': true,
+                                'name': 'port',
+                                'type': 'Object'
+                            }
+                        ],
+                        returnType: 'Void',
+                        returnDescription: undefined
+                    }]
+                },
                 roregion: {
                     interfaces: [{
                         name: 'ifDraw2D',
                         url: 'https://developer.roku.com/docs/references/brightscript/interfaces/ifdraw2d.md'
                     }]
                 }
-            },
+            } as Record<string, Partial<BrightScriptComponent>>,
             events: {},
             interfaces: {
                 ifsgnodechildren: {
@@ -1760,6 +1779,10 @@ interface BrightScriptComponent extends PossiblyDeprecated {
     description: string;
     constructors: Array<Signature>;
     interfaces: Reference[];
+    /**
+     * Most components only get their methods from interfaces, but occasionally we need to attach one
+     */
+    methods: Func[];
     events: Reference[];
 }
 
@@ -1860,4 +1883,3 @@ interface ElementFilter {
 
 //run the builder
 new Runner().run().catch((e) => console.error(e));
-

src/SemanticTokenUtils.spec.ts

@@ -72,6 +72,14 @@ describe('SemanticTokenUtils', () => {
                 SemanticTokenModifiers.documentation //idx=8
             ])).to.eql(0b100001001);
         });
+
+        it('properly handles deprecated and another', () => {
+            expect(getModifierBitFlags([
+                SemanticTokenModifiers.declaration, //idx=0
+                SemanticTokenModifiers.static, //idx=3
+                SemanticTokenModifiers.documentation //idx=8
+            ])).to.eql(0b100001001);
+        });
     });
 });
 

src/SymbolTypeFlag.ts

@@ -5,5 +5,6 @@ export const enum SymbolTypeFlag {
     optional = 4,
     private = 8,
     protected = 16,
-    postTranspile = 32
+    postTranspile = 32,
+    deprecated = 64
 }

src/bscPlugin/semanticTokens/BrsFileSemanticTokensProcessor.spec.ts

@@ -489,6 +489,20 @@ describe('BrsFileSemanticTokensProcessor', () => {
         ]);
     });
 
+    it('marks setPort as deprecated', () => {
+        const file = program.setFile<BrsFile>('source/main.bs', `
+            sub main()
+                url = createObject("roUrlTransfer") as roUrlTransfer
+                url.setPort(80)
+            end sub
+        `);
+        program.validate();
+        expectSemanticTokensIncludes(file, [
+            // url.|setPort|(80)
+            [SemanticTokenTypes.method, 3, 20, 3, 27, [SemanticTokenModifiers.deprecated]]
+        ]);
+    });
+
     it('works for `new` statement', () => {
         const file = program.setFile<BrsFile>('source/main.bs', `
             class Person

src/bscPlugin/semanticTokens/BrsFileSemanticTokensProcessor.ts

@@ -79,6 +79,11 @@ export class BrsFileSemanticTokensProcessor {
         if (symbolType?.isResolvable()) {
             let info = this.getSemanticTokenInfo(node, symbolType, extraData);
             if (info) {
+                //mark as deprecated if applicable
+                if ((extraData.flags & SymbolTypeFlag.deprecated)) { // eslint-disable-line no-bitwise
+                    info.modifiers ??= [];
+                    info.modifiers.push(SemanticTokenModifiers.deprecated);
+                }
                 this.addToken(token, info.type, info.modifiers);
             }
         }

src/files/BrsFile.spec.ts

@@ -5133,4 +5133,15 @@ describe('BrsFile', () => {
             ).to.be.false;
         });
     });
+
+    it('handles deprecated .setPort() on rourltransfer', () => {
+        program.setFile('source/main.bs', `
+            function main()
+                url = createObject("roUrlTransfer") as roUrlTransfer
+                url.setPort(80)
+            end function
+        `);
+        program.validate();
+        expectZeroDiagnostics(program);
+    });
 });

src/roku-types/data.json

@@ -1,5 +1,5 @@
 {
-    "generatedDate": "2024-05-30T13:07:44.633Z",
+    "generatedDate": "2024-06-04T12:31:13.858Z",
     "nodes": {
         "animation": {
             "description": "Extends [**AnimationBase**](https://developer.roku.com/docs/references/scenegraph/abstract-nodes/animationbase.md\n\nThe Animation node class provides animations of renderable nodes, by applying interpolator functions to the values in specified renderable node fields. For an animation to take effect, an Animation node definition must include a child field interpolator node ([FloatFieldInterpolator](https://developer.roku.com/docs/references/scenegraph/animation-nodes/floatfieldinterpolator.md\"FloatFieldInterpolator\"), [Vector2DFieldInterpolator](https://developer.roku.com/docs/references/scenegraph/animation-nodes/vector2dfieldinterpolator.md\"Vector2DFieldInterpolator\"), [ColorFieldInterpolator](https://developer.roku.com/docs/references/scenegraph/animation-nodes/colorfieldinterpolator.md\"ColorFieldInterpolator\")) definition for each renderable node field that is animated.\n\nThe Animation node class provides a simple linear interpolator function, where the animation takes place smoothly and simply from beginning to end. The Animation node class also provides several more complex interpolator functions to allow custom animation effects. For example, you can move a graphic image around the screen at differing speeds and curved trajectories at different times in the animation by specifying the appropriate function in the easeFunction field (quadratic and exponential are two examples of functions that can be specified). The interpolator functions are divided into two parts: the beginning of the animation (ease-in), and the end of the animation (ease-out). You can apply a specified interpolator function to either or both ease-in and ease-out, or specify no function for either or both (which is the linear function). You can also change the portion of the animation that is ease-in and ease-out to arbitrary fractional values for a quadratic interpolator function applied to both ease-in and ease-out.",
@@ -8813,6 +8813,24 @@
                     "url": "https://developer.roku.com/docs/references/brightscript/interfaces/ifurltransfer.md"
                 }
             ],
+            "methods": [
+                {
+                    "deprecatedDescription": "Use .SetMessagePort instead. Some legacy objects still implement the older `SetPort` function, but apps should not be using it.",
+                    "description": "DEPRECATED: use `.SetMessagePort()` instead. \n\nSets the roMessagePort to be used to receive events",
+                    "isDeprecated": true,
+                    "name": "SetPort",
+                    "params": [
+                        {
+                            "default": null,
+                            "description": "The port to be used to receive events.",
+                            "isRequired": true,
+                            "name": "port",
+                            "type": "Object"
+                        }
+                    ],
+                    "returnType": "Void"
+                }
+            ],
             "name": "roUrlTransfer",
             "url": "https://developer.roku.com/docs/references/brightscript/components/rourltransfer.md"
         },

src/types/BuiltInInterfaceAdder.ts

@@ -48,6 +48,19 @@ export class BuiltInInterfaceAdder {
         }
         const interfacesToLoop = builtInComponent.interfaces ?? [builtInComponent];
 
+        //add any direct methods from this component to the member table
+        if (this.isBrightScriptComponent(thisType)) {
+            for (const method of builtInComponent.methods ?? []) {
+                const methodFuncType = this.buildMethodFromDocData(method, overrides, thisType);
+                let flags = SymbolTypeFlag.runtime;
+                //set the deprecated flag if applicable
+                if ((method as any).isDeprecated) {
+                    flags |= SymbolTypeFlag.deprecated; // eslint-disable-line no-bitwise
+                }
+                builtInMemberTable.addSymbol(method.name, { description: method.description, completionPriority: 1 }, methodFuncType, flags);
+            }
+        }
+
         for (const iface of interfacesToLoop) {
             const lowerIfaceName = iface.name.toLowerCase();
             const ifaceData = (interfaces[lowerIfaceName] ?? events[lowerIfaceName]) as BRSInterfaceData;
@@ -147,7 +160,18 @@ export class BuiltInInterfaceAdder {
         }
     }
 
-    static getMatchingRokuComponent(theType: BscType) {
+    static isBrightScriptComponent(theType: BscType) {
+        const componentName = this.getMatchingRokuComponentName(theType);
+        if (!componentName) {
+            // No component matches the given type
+            return;
+        }
+        const lowerComponentName = componentName.toLowerCase();
+        return !!components[lowerComponentName];
+    }
+
+    //the return type is a union of the three data types. Just pick the first item from each collection, as every item in the collection should have the same shape
+    static getMatchingRokuComponent(theType: BscType): typeof components['roappinfo'] & typeof interfaces['ifappinfo'] & typeof events['rourlevent'] {
         const componentName = this.getMatchingRokuComponentName(theType);
         if (!componentName) {
             // No component matches the given type
@@ -177,7 +201,12 @@ export class BuiltInInterfaceAdder {
         }
         for (const method of builtInNode.methods ?? []) {
             const methodFuncType = this.buildMethodFromDocData(method, null, thisType);
-            memberTable.addSymbol(method.name, { description: method.description, completionPriority: 1 }, methodFuncType, SymbolTypeFlag.runtime);
+            let flags = SymbolTypeFlag.runtime;
+            //set the deprecated flag if applicable
+            if (method.isDeprecated) {
+                flags |= SymbolTypeFlag.deprecated; // eslint-disable-line no-bitwise
+            }
+            memberTable.addSymbol(method.name, { description: method.description, completionPriority: 1 }, methodFuncType, flags);
         }
     }