I just indexed android 'froyo' javadoc in kiwidoc and it was quite a challenge.

1. Downloading the source code

You have to go to http://source.android.com/ to find instructions on how to get it. This part is actually quite challenging because there are lots of steps to simply 'get it'. I understand why it is being done this way: you end up with a ready to develop/contribute environment. On the other end, if you simply want to look at the source code it is quite complex and potentially time consuming.

2. Downloading the 'correct' version of the source code

I know it is written in the manual but it is not very intuitive to download the correct version. Under the cover, it uses git but it is wrapped by a high level command called repo. When you use plain git in a project, you simply clone the project and then you can switch to a branch. When you use the repo command, you end up with an error message if you try to follow the git paradigm.

> repo branches
   (no branches)
> repo checkout froyo
error: no project has branch froyo

It is very important to 'clone' with the correct version originally:

repo init -u git://android.git.kernel.org/platform/manifest.git -b froyo 

I am sure there are very good reasons to do it this way, but it would certainly be easier if the command were to behave like git.

3. Compiling android

I use a Mac OS X machine (Snow Leopard) and bumped into a lot of issues:

• Snow Leopard is not supported
• It requires a case-sensitive file system (which is not the default on Mac OS X)
• It requires Java 1.5 (which is eol now...)

Thankfully I had an old drive with Leopard on it and was able to eventually compile it using this version of the OS and creating a case-sensitive partition.

4. Make

For my own purpose I actually only needed the javadoc and the java source code. After running a full build (I just issued the make command) which took several hours to run (no kidding), there was no javadoc. Not being very familiar with make, it took me a while to figure out that you can run the command:

make -p > android-make.db

which "Print make's internal database". In this case it generated a 156MB file! Sifting through this file, I was able to identify the command I needed:

make offline-sdk-docs

which generated the javadoc.

5. kiwidoc generation

By slightly tweaking the javadoc command in the make file, I was able to generate the information I needed for kiwidoc: mainly all the source files to take into account as well as the classpath. Once I had this information, actually indexing it tooks 20s.

6. Android versions

I think that the android version naming, although I understand why it is being done this way, is quite confusing:

• Platform version (2.2 is the 'current' latest one)
• API Level (8 is the 'current' latest one)
• Code Name (froyo is the 'current' latest one)

Code names are cool but it make it very hard to remember to which actual version they tie to: the Android API Levels page does not even mention codenames (so how do you know which version is 'eclair' for example ?). In kiwidoc, I chose to use the api level as the version of the library because it is what reflects what you program against: there could be a new platform version (ex: 2.2.1) without a change in api level. What matters from an application developer point of view is the api level.

7. Conclusion

It took me a really long time to index froyo (api level 8) but I succeeded which is very satisfying. I also 'promoted' the android platform all the way to the home page.