Hi, this has been noted by many people previously, but I thought I'd have a little rant about it. Simply put, the Android SDK documentation is shockingly incomplete. I can't believe Google doesn't have the resources to employ someone full-time to work on it. Here are just a few examples:
1. You need to call ItemizedOverlay.populate() even if you have added no items. This is mentioned no-where, and I've even seen people create crazy work-arounds because they didn't know it. 2. populate() isn't explained at all well. Let's compare a few function descriptions with what *I* would write: ItemizedOverlay intro, current version: "A base class for an Overlay which consists of a list of OverlayItems. This handles sorting north-to-south for drawing, creating span bounds, drawing a marker for each point, and maintaining a focused item. It also matches screen-taps to items, and dispatches Focus-change events to an optional listener. " My version: "ItemizedOverlay is an Overlay that allows you to easily draw small collections of [OverlayItem]s on top of the map. Typically the items will be some kind of pin or marker. A default [Drawable] to use can be passed to the constructor, and individual [OverlayItem]s can have specific [Drawable]s. This class handles sorting the items north-to-south so that the overlap as expected, and drawing a marker for each point. It also maintains a focused item, matches screen-taps to items, and dispatches Focus-change events to an optional listener. Typically it is subclassed and used as described below. See the documentation for populate() and createItem() for further information on how to specify the [OverlayItem]s. <then I would give an example of deriving a simple class from ItemizedOverlay, but I'm not paid to write this so meh>" ItemizedOverlay.populate(), current version: "Utility method to perform all processing on a new ItemizedOverlay. Subclasses provide Items through the createItem(int) method. The subclass should call this as soon as it has data [note that this is *wrong*!], before anything else gets called." My version: "ItemizedOverlay maintains an internal cache of [OverlayItem]s in order to draw them efficiently. This function must be called in order to populate the internal cache. Note that it must be called before the draw() method is even if you have added no items. When it is called it first uses ItemizedOverlay.size() to determine how many [OverlayItem]s there are to draw. You must override this method in your subclass. Once the number of items has been determined it calls ItemizedOverlay.createItem(int i) for i=0 to size() in order to retrieve each [OverlayItem]. These items are then sorted from north to south to facilitate drawing. Whenever you change the items to be drawn you must call populate() in order to update the cache." Actually I've just noted that that description isn't quite true and has caused a bug in my program - size() is apparently only ever called once. This is pretty stupid but hey, my point stands. 3. At http://developmentality.net/ there is a note about how setMarker() doesn't work unless you set the bounds on the drawable. This should clearly be mentioned in the documentation. 4. fill_parent, wrap_content, gravity and so on aren't adequately explained *at all*. 5. Not a documentation issue, but boundCenterBottom() should be really be public. 6. I strongly encourage you to look at the documentatio for ProgressDialog. It is truly shocking: http://developer.android.com/reference/android/app/ProgressDialog.html#getMax() I know there are a lot of classes, but *really*. 7. There are so many classes where the documentation is the type that I would write *to myself* as I was writing the code. e.g. Bundle is described as "A mapping from String values to various Parcelable types.". That's it. Helpful. This mailing list is clearly too high volume for anyone from Google to read, but I feel better for having ranted. Back me up here people. :-) -- You received this message because you are subscribed to the Google Groups "Android Developers" group. To post to this group, send email to android-developers@googlegroups.com To unsubscribe from this group, send email to android-developers+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/android-developers?hl=en
