Blockly Documentation Confusion

35 views
Skip to first unread message

Colleen King

unread,
Nov 29, 2022, 1:31:45 PM11/29/22
to Blockly
When viewing the Blockly Reference/documentation and coming across answers to my questions related to Blockly, I've noticed that sometimes there is a discrepancy between what is shown in the Reference and what is actually available. 

For example, in this answer, they advise using `workspace.getFlyout()`. However, when viewing the Blockly Workspace class documentation, it does not list `getFlyout()` as a possible method.

I was wondering if there is an available place that would show all of the available methods and properties. I'm not quite sure where to look! How do people know these methods or properties exist without it being listed? Or is the Blockly documentation just not up-to-date? 

Just curious if there is something that I am missing!

Neil Fraser

unread,
Nov 29, 2022, 2:28:23 PM11/29/22
to blo...@googlegroups.com
Excellent question.

getFlyout is actually defined on WorkspaceSvg, rather than the parent class of Workspace.  Here's the code:
Unless you are using headless stuff in node.js, every workspace you encounter will be a WorkspaceSvg, not just a Workspace.  Likewise, every block you encounter will be a BlockSvg, not just a Block.  So that's why the documentation for Workspace doesn't list getFlyout.

However the documentation for WorkspaceSvg also doesn't list getFlyout!  This is because this method (as well as many others) has the '@internal' annotation, which stops it from being documented.  The intent is that we don't want to spam the documentation with a ton of functions that nobody would use (for example WorkspaceSvg.setMetricsManager).  But there are definitely some that are miscategorized.  I'll remove the @internal annotation from WorkspaceSvg.getFlyout, WorkspaceSvg.getToolbox, and Flyout.getWorkspace right now.

So in summary:
1) Don't forget to check the SVG subclasses of Block and Workspace when checking the API.
2) Use the source when you are digging into the more obscure areas of Blockly.



--
You received this message because you are subscribed to the Google Groups "Blockly" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blockly+u...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/blockly/1841e6da-b763-4746-b36f-c61812b21c29n%40googlegroups.com.


--
Neil Fraser, Switzerland
https://neil.fraser.name

Neil Fraser

unread,
Nov 29, 2022, 2:34:50 PM11/29/22
to blo...@googlegroups.com
And we got a wicked number for the change: https://github.com/google/blockly/pull/6666

Colleen King

unread,
Nov 29, 2022, 4:05:05 PM11/29/22
to Blockly
elmo-fire.gif

(Also thank you for the great explanation and for your help! Sincerely appreciate it)

feni...@google.com

unread,
Nov 29, 2022, 5:19:53 PM11/29/22
to Blockly
And if you find an @internal function that you do want to use, please tell us by filing an issue on GitHub. Internal and private properties are fair game for us to rename internally without deprecation warnings.

Rachel

Reply all
Reply to author
Forward
0 new messages