It is both -- and neither. Yes, the API docs in the Reference Tab can be amazingly terse at times. But on the more fundamental classes/ interfaces, they are not so terse. So "absolute sham" is certainly an overstatement. Take a a look. for example, at the documentation on Context or on TextView.
Now in your example, the reason it is so terse is perhaps merely that the functions you list are all accessor functions, named following the very common Java convention. This then, would be yet another example of how Android expects you to have a fairly good acquaintance with Java. There is not a whole lot to say about what 'getMaximumRange()' returns. Obviously,it returns a maximum range. Less obvious is what the units are; but it worst comes to worst, you can figure that out by actually using the accessor. Also, the latest version (1.6) does say a little more than you give credit for: it actually says, "maximum range of the sensor in the sensor's unit." Now saying "in the sensor's unit" may sound hopelessly non-committal, but it reminds the reader of an important point: the units are hardware dependent. So they cannot be documented in more detail here. On Oct 22, 2:00 am, gmseed <gms...@gmail.com> wrote: > Is it me or is the Android Developer Reference documentation an > absolute sham? > > Take the Sensor page, which lists the public methods: > > float getMaximumRange() > String getName() > float getPower() > float getResolution() > int getType() > String getVendor() > int getVersion() > > Not a single comment as to what these do. Readers must be expected to > be mind readers. > > Then take SensorListener, which provides a few comments on the > accelermoeter, magnetic and orientation sensors but no mention of the > other sensors. > > When I run an application with onSensorChanged (int sensor, float[] > values) it outputs 6 values and not 3 as the documentation would > suggest. > > Etc, etc, > > Developers are expected to fish around and use guess work to try and > figure out what's actually going on. > > Working with 4x4 rotation axis matrices is tricky stuff and needs > detailed explanations. > > With all of Google's backing you'd think the documentation would be > excellent. > > Consider the alternative system of Qt by Trolltech. The "Assitant" > documentation is excellent and has led to a big take up of Qt. If > Google wants developers to get up to speed fast on Android then they > should phone the Trollech documenting team asap. > > I gather from reading previous posts that this documentation issue is > not new and has been around since the start of Android. Clearly then > somebody at Google has a strange idea as to what documenting an API > means. > > The Android system is amazing but really let down by its developer > documentation. --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Android Beginners" group. To post to this group, send email to android-beginners@googlegroups.com To unsubscribe from this group, send email to android-beginners+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/android-beginners?hl=en -~----------~----~----~----~------~----~------~--~---
