Improve sig snippet to display alias statement

common-docs/reference/arrays/pop.md

@@ -6,34 +6,52 @@ Remove and return the last element from an array.
 ["hello"].pop()
 ```
 
+Remove the last element from an array but don't return it.
+
+```sig
+["hello"]._popStatement()
+```
+
 The last element in the array is removed, so the array becomes smaller by one element.
 
 If you have an array with 4 numbers, like 1, 2, 3, and 4, you remove the last number from the array
 by _popping_ it off of the end. To pop the number from the array in blocks, do this:
 
 ```block
-let thoseNumbers = [1, 2, 3, 4];
-let lastNumber = thoseNumbers.pop();
+let thoseNumbers = [1, 2, 3, 4]
+let lastNumber = thoseNumbers.pop()
 ```
 
 ## Returns
 
 * The last element in the array.
 
+### ~reminder
+
+#### **pop** statement
+
+The ``||arrays:pop||`` **statement** only removes the last element from the array. It doesn't return it.
+
+```block
+["a", "b", "c"]._popStatement()
+```
+
+### ~
+
 ## Example
 
 Clean out your junk drawer but check if the scissors are in there. Do this by removing them from your list items in the drawer.
 
 ```blocks
-let found = false;
-let junk = ["paper clip", "pencil", "notepad", "glue", "scissors", "screw driver"];
+let found = false
+let junk = ["paper clip", "pencil", "notepad", "glue", "scissors", "screw driver"]
 while (junk.length > 0) {
     if (junk.pop() == "scissors") {
-        found = true;
+        found = true
     }
 }
 ```
 
 ## See also
 
-[push](/reference/arrays/push), [shift](/reference/arrays/shift)
+[push](/reference/arrays/push), [shift](/reference/arrays/shift)

common-docs/reference/arrays/remove-at.md

@@ -6,6 +6,12 @@ Remove and return an element from an array at some position.
 [""].removeAt(0)
 ```
 
+Remove an element from an array at some position but don't return it.
+
+```sig
+[""]._removeAtStatement(0)
+```
+
 The size of the array shrinks by one. The element is removed from the array at the position you want. All the other elements after it are moved (shifted) to down to the next lower position. So, an array that has the numbers
 `4, 5, 9, 3, 2` will be `4, 5, 3, 2` if `9` is removed from the array at index `2`. It looks like this in blocks:
 
@@ -22,6 +28,18 @@ let item = myNumbers.removeAt(2)
 
 * the element in the array from the position you chose.
 
+### ~reminder
+
+#### **remove At** statement
+
+The ``||arrays:remove at||`` **statement** only removes an element from the array. It doesn't return it.
+
+```block
+["a", "b", "c"]._removeAtStatement(0)
+```
+
+### ~
+
 ## Example
 
 Remove the most dangerous level of radiation from the list.
@@ -34,5 +52,4 @@ let unzapped = radLevels.removeAt(level)
 
 ## See also
 
-[remove at (no return value)](/reference/arrays/remove-at-statement),
-[insert at](/reference/arrays/insert-at)
+[insert at](/reference/arrays/insert-at)

common-docs/reference/arrays/shift.md

@@ -6,35 +6,51 @@ Remove and return the first element from an array.
 [""].shift()
 ```
 
+Remove the first element from an array but don't return it.
+
+```sig
+[""]._shiftStatement()
+```
+
 The first element in the array is removed, so the array becomes smaller by one element.
 
 If you have an array with 4 numbers, like 1, 2, 3, and 4, you remove the first number from the array
 by _shifting_ it from the front. To shift the number from the array in blocks, do this:
 
 ```block
-let thoseNumbers = [1, 2, 3, 4];
-let firstNumber = thoseNumbers.shift();
+let thoseNumbers = [1, 2, 3, 4]
+let firstNumber = thoseNumbers.shift()
 ```
 
 ## Returns
 
 * the first element in the array.
 
+### ~reminder
+
+#### **shift** statement
+
+The ``||arrays:shift||`` **statement** only removes the first element from the array. It doesn't return it.
+
+```block
+["a", "b", "c"]._shiftStatement()
+```
+
+### ~
 ## Example
 
 Find out how many odd numbers there are as you remove all the numbers from a list.
 
 ```blocks
-let odds = 0;
-let ints = [45, 78, 98, 3, 5, 6, 12, 643, 0, 34, 4];
+let odds = 0
+let ints = [45, 78, 98, 3, 5, 6, 12, 643, 0, 34, 4]
 while (ints.length > 0) {
     if ((ints.shift() % 2) > 0) {
-        odds++;
+        odds++
     }
 }
 ```
 
 ## See also
 
 [unshift](/reference/arrays/unshift), [pop](/reference/arrays/pop)
-

common-docs/reference/arrays/unshift.md

@@ -1,24 +1,43 @@
 # unshift
 
-Add an element to the front of an array.
+Add an element to the front of an array and return the new length of the array.
 
 ```sig
 [""].unshift("hello")
 ```
+Add an element to the front of an array but don't return the new length of the array.
+
+```sig
+[""]._unshiftStatement("hello")
+```
 
 You might have an array with 3 numbers, like 1, 2, and 3. If you want to add another number to the front,
 then you _unshift_ it into the array. You do it like this:
 
 ```block
-let thoseNumbers = [1, 2, 3];
-let head = 0;
-head = thoseNumbers.unshift(0);
+let thoseNumbers = [1, 2, 3]
+let arrayLength = thoseNumbers.unshift(0)
 ```
 
 ## Parameters
 
 * **item**: the element to add to the front of the array.
 
+## Returns
+
+* the new length of the array.
+
+### ~reminder
+
+#### **shift** statement
+
+The ``||arrays:unshift||`` **statement** only adds an element to the front of the array. It doesn't the array length.
+
+```block
+["a", "b", "c"]._shiftStatement()
+```
+
+### ~
 ## Example
 
 Make an array that simulates a train. Place the parts of the train in the right order.
@@ -46,4 +65,4 @@ while (parts.length > 0) {
 
 ## Sea also
 
-[shift](/reference/arrays/shift), [push](/reference/arrays/push)
+[shift](/reference/arrays/shift), [push](/reference/arrays/push)

libs/pxt-common/pxt-core.d.ts

@@ -245,7 +245,7 @@ interface Array<T> {
     _shiftStatement(): void;
 
     /** Remove the element at a certain index. */
-    //% help=arrays/remove-at-statement
+    //% help=arrays/remove-at
     //% shim=Array_::removeAt weight=14
     //% blockId="array_removeat_statement" block="%list| remove value at %index" blockNamespace="arrays"
     //% blockAliasFor="Array.removeAt"

pxtrunner/renderer.ts

@@ -481,7 +481,8 @@ function renderSignaturesAsync(options: ClientRenderOptions): Promise<void> {
         let cjs = r.compileProgram;
         if (!cjs) return;
         let file = cjs.getSourceFile(pxt.MAIN_TS);
-        let info = decompileCallInfo(file.statements[0]);
+        let [mainStatement, ...aliasStatements] = file.statements
+        let info = decompileCallInfo(mainStatement);
         if (!info || !r.apiInfo) return;
         const symbolInfo = r.apiInfo.byQName[info.qName];
         if (!symbolInfo) return;
@@ -497,6 +498,22 @@ function renderSignaturesAsync(options: ClientRenderOptions): Promise<void> {
         const pySig = pxt.appTarget?.appTheme?.python && ts.pxtc.service.displayStringForSymbol(symbolInfo, /** python **/ true, r.apiInfo).split("\n")[1];
         const py: JQuery = pySig && $('<code class="lang-python highlight"/>').text(pySig);
         if (options.snippetReplaceParent) c = c.parent();
+
+        // add alias svgs
+        let svgs = $('<div style="display:flex;flex-direction:column;gap:1em;" />').append(s);
+        svgs = aliasStatements.reduce((parentElement, statement) => {
+            let aliasInfo = decompileCallInfo(statement);
+            if (!aliasInfo) return parentElement;
+            const aliasSymbolInfo = r.apiInfo.byQName[aliasInfo.qName];
+            if (!aliasSymbolInfo) return parentElement;
+            if (aliasSymbolInfo.attributes.blockAliasFor !== info.qName) return parentElement;
+            let aliasBlock = Blockly.Blocks[aliasSymbolInfo.attributes.blockId];
+            let aliasXml = aliasBlock?.codeCard?.blocksXml || undefined;
+            const aliasBlocksHtml = aliasXml ? render(aliasXml) : r.compileBlocks?.success ? r.blocksSvg : undefined;
+            const aliasSvg = aliasBlocksHtml ? $(aliasBlocksHtml as HTMLElement) : undefined;
+            return parentElement.append(aliasSvg);
+        }, svgs);
+
         // add an html widge that allows to translate the block
         if (pxt.Util.isTranslationMode()) {
             const trs = $('<div class="ui segment" />');
@@ -507,7 +524,7 @@ function renderSignaturesAsync(options: ClientRenderOptions): Promise<void> {
                 trs.append($('<div class="ui message">').text(symbolInfo.attributes.jsDoc));
             trs.insertAfter(c);
         }
-        fillWithWidget(options, c, js, py, s, r, { showJs: true, showPy: true, hideGutter: true });
+        fillWithWidget(options, c, js, py, svgs, r, { showJs: true, showPy: true, hideGutter: true });
     }, { package: options.package, snippetMode: true, aspectRatio: options.blocksAspectRatio, assets: options.assetJSON });
 }