One definite criticism I have of the Android reference is descriptions which don't actually clarify the thing that they're meant to be documenting. My all-time favorite is from http://developer.android.com/reference/android/graphics/drawable/Drawable.html:
'A Drawable is a general abstraction for "something that can be drawn."' If that's not a circular definition, I don't know what is. I've been in Android development since 1.1 and I am still a bit hazy on exactly what a Drawable IS. Overall, you don't need to look very far to find documentation which is just really lacking. Take a look at http://developer.android.com/reference/android/content/Entity.html, an example I found after about 30 seconds of searching. What's an Entity? 'A representation of a item using ContentValues. It contains one top level ContentValue plus a collection of Uri, ContentValues tuples as subvalues.' And then, of the 4 methods, there is NO documentation for 3 of them - the only one documented is toString(), and that's the same cut-n-paste description as for any other Object.toString(). One that I've had to actually stop using - for lack of decent documentation - is WallpaperManager.sendWallpaperCommand(). The first parameter, windowToken, is documented as 'The window who these offsets should be associated with, as returned by View.getWindowToken().' Problem is, if you want to send a command to the system wallpaper, there's NO indication of how to get a windowToken for the Home screen. None. Here's another one: http://developer.android.com/reference/android/content/pm/ServiceInfo.html Of its 4 methods, dump() and writeToParcel() have no documentation whatsoever, toString() was discussed above, and describeContents() is documented as: 'Describe the kinds of special objects contained in this Parcelable's marshalled representation. Returns a bitmask indicating the set of special object types marshalled by the Parcelable.' Again, this is just carbon-copy, with no further information on the bitmask or the "special object types". Here's a classic: http://developer.android.com/reference/android/os/Debug.MemoryInfo.html EVERY method here is "documented" with a one-line "description" which is barely more helpful than the method name itself. Typical example: 'public int getTotalPss () Return total PSS memory usage in kB.' Or look at the docs for OpenGL. They're almost non-existent; you need to go track down OpenGL information elsewhere on the web, then try figure out which subset Android implements, and relate it back to Android data types. I could go on and on. Over the last 18 months, I've found many more egregious examples that I can't lay my hands on at the moment. But suffice it to say, these docs DO look like Google isn't trying here. String On Sep 14, 8:45 pm, TreKing <[email protected]> wrote: > On Tue, Sep 14, 2010 at 2:30 PM, DanH <[email protected]> wrote: > > Not really. A reference should be coherent and well-organized. > > What's so incoherent and disorganized about the current documentation? > Specifics might help bring more attention to the parts that need it. > > > I've run across several diagrams of the application state flow, for > > instance, and most are clearly wrong > > In the official docs? Can you point them out? > > > And descriptions (no diagrams that I've found) of the Intent resolution > > algorithm are similarly inconsistent. > > Can you point these out as well? > > --------------------------------------------------------------------------- > ---------------------- > TreKing <http://sites.google.com/site/rezmobileapps/treking> - Chicago > transit tracking app for Android-powered devices -- You received this message because you are subscribed to the Google Groups "Android Developers" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/android-developers?hl=en
