Compiled Corrections/Requests for Clarification in API Documentation

[Eunomiac]

The API docs are really excellent, but there are some areas that could use cleaning up, clarification or other improvement. Rather than spam the issue tracker with a post for each, I intend to post things as I find them to this issue only. (If you'd prefer I do submit individual issues for each distinct correction, please let me know and I'll happily comply.)

• [🔗] visibility Attribute Definition --- Changing visibility via script works inconsistently and isn't advised; a note to this effect here would prevent a lot of confusion. Users should be advised to clone their UI elements for each player color, setting visibility explicitly in the XML, and then hiding/showing/manipulating each player's personal UI, as opposed to creating a single UI element and trying to switch visibility from player to player in script
• [🔗] image Attribute Definition --- Users can also input a URL pointing to an image, in addition to assets named in the Asset Manager. These URLs can be retrieved easily from the Cloud Manager with a click, but the main difference (I believe) is that images defined by URL are not preloaded when players connect to the game: This should be noted too, since users may want to use or avoid this behavior depending on the needs of their script.
• Comprehensive Attribute Lists --- Statements like "some, but not all, elements have the following attributes" [🔗] are not helpful. Instead, I suggest adding a subheader to the sections describing each element. This subheader should contain simple, one-word links the groups of attributes that apply to the element, removing any confusion as to what attributes will be effective and which will not, almost like an "Inherits from..." line in the documentation of a modular API.

I had more, but unfortunately I haven't been taking notes and this is all I've got at the moment. Again, I'll reply to this issue with more as I find them.