I’m working on an Android app and the documentation didn’t stop me making a stupid mistake. If it weren’t open-source, that might have been a problem.
For the first time in my Android life, I wanted to use a Notification. The instructions are straightforward, except for I was worried about what size graphic to use in the pull-down notification (as opposed to in the status bar); it didn’t seem like they could be the same size, and the nice list of icon sizes didn’t have one labeled “Notification pulldown”. So I tried guessing but that didn’t work out very well. Worse than that, the usual plan B, typing “notification pulldown icon size” into Google, didn’t help much.
Then I looked at the other notifications in the pulldown and noticed that one of them, with a nice icon, said “USB debugging connected”. So I hopped over to my AOSP source tree and said:
find . -name '*.xml' -print | xargs egrep 'USB debugging connected'
The output from some
strings.xml file gave the string’s internal name:
adb_active_notification_title. So I said:
find . -name '*.java' -print | \ xargs egrep adb_active_notification_title
After which I knew that the code I wanted to see was in a file called
NotificationManagerService.java, seven (!) levels deep in the
source tree. I opened that up, searched for
adb_active, and was
looking at notification-setup code. Right away I learned a couple of
useful tricks for my own app; then I noticed that the icon it was
jamming into the notification was called
find . -print | grep stat_sys_adb
Which turned up a couple of PNG files, and a quick glance told me that the hdpi version was 38x38, the mdpi 25x25. Which is to say, yep, the same icon for status bar and notification drop-down. And the framework arranges to render them at whatever the appropriate size is.
There you go. In an ideal world, I’d have been smart enough to deduce that since they didn’t say anything about different icon sizes, I could just use the same one in both places. In some future even more ideal world, the AI-driven documentation would deduce that I was overthinking it and say “Yes, you moron, you can use the same icon for status bar and drop-down.”
We live in a non-ideal world. In such a world, Open Source wins.
Your Opinions · I just got around to moderating comments, and to save space, let me just report, without copying them all in, that there were a bunch of comments saying “You’re horrible people because your documentation isn’t complete and I might have to grep the source” and another pile saying “You’re horrible people because you haven’t released 100% of the source so there are parts I can’t grep.”
I did accept comments that weren’t dupes of one of those gripes.