Just this morning I came across this (in http://developer.android.com/guide/topics/ui/themes.html):
'The R.style reference, however, is not well documented and does not thoroughly describe the styles, so viewing the actual source code for these styles and themes will give you a better understanding of what style properties each one provides.' Beautiful! We have the documentation ITSELF admitting that it's woefully incomplete! String On Sep 14, 11:00 pm, String <[email protected]> wrote: > 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 > fromhttp://developer.android.com/reference/android/graphics/drawable/Draw... > > '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 > athttp://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... > > 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
