Dashboard’s behaviour (expressed through methods and properties) is farely well documented, but I’ve been breaking my head over a number of things, which I eventually had to find out through trial and error. Had they been included in the official Dashboard reference…

Below is a list of the quirky behaviour I’ve encountered while developing the widgets on this site.

• widget.onshow fires on: showing the Dashboard (documented), placing a new instance on the Dashboard (undocumented). The latter undocumented feature would also fire when the widget would be “installed” or “replaced”, which I believe is similar to placing a new instance.
• reloading (CMD+R) the widget is apparently not the same as placing a new instance on the Dashboard, as widget.onshow is not fired. (undocumented)
• widget.onremove fires when a widget is replaced with (another version of) the same widget. Not so handy when you use the widget.identifier to allow for multiple instances of the same widget, all with their own preferences. (undocumented)
• the widget.identifier is not retained when a widget is replaced with (another version of) the same widget. Moreover, when multiple instances are present at one time, they are all replaced by one (in total) virgin instance. Again, not so handy (see previous remark) (undocumented)

So, I hope this info will somehow either be included with the official documentation (I’ve filed a feedback report at Apple’s website) or you’ll be able to find it here.