AndroidDroidDoc

Android DroidDoc

The Android build system contains a makefile called droiddoc.mk that can be used to generate documentation, java API
stubs and API xml files.

It can generate two kinds of documentation. The first kind is the standard Java javadoc documentation as well known in the
Java world. The second kid create more custom documentation by using a special doclet and templating engine.

The special Android doclet version extends the standard doclet with a new set of options and a new templating language
that make use of the clearsilver language-neutral HTML template system.

droiddoc.mk options

Variable	Description
LOCAL_IS_HOST_MODULE	Defines if the given source code need to run on the SDK/PC side or the Target/Emulator. When set to true the LOCAL_JAVA_LIBRARIES AND LOCAL_STATIC_LIBRARIES are not taken into account and the location for the documentation will be prefixed with HOST_
LOCAL_DROIDDOC_SOURCE_PATH	Source path to be used a root for the javadoc process. Default to LOCAL_PATH (the path of your project)
LOCAL_SRC_FILES	The list of files to be documented. Only files with the Java extension are taken into account during the javadoc generation process but all files listed here will be taken info account during the depedency handling.
LOCAL_DROIDDOC_TEMPLATE_DIR	Clearsilver template directory. Defaults to the templates directory found under the build/tools/droiddoc directory
LOCAL_DROIDDOC_CUSTOM_TEMPLATE_DIR	Clearsilver allows you to extend a base template with some customisation that can be put is a different directory. For example when the standard sdk documentation uses a different header and navigation. You can do the same
LOCAL_DROIDDOC_ASSET_DIR
LOCAL_DROIDDOC_CUSTOM_ASSET_DIR
LOCAL_DROIDDOC_OPTIONS	Additional parameters to pass to the javadoc command line like
LOCAL_DROIDOC_USE_STANDARD_DOCLET
LOCAL_DROIDDOC_HTML_DIR	Directory used as html source for clearsliver during the documentation generation. This source directory can be empty but the value needs to be assigned in order for DroidDoc to generate the package.html file that is used in the default clearsilver template
LOCAL_JAVA_LIBRARIES
LOCAL_STATIC_LIBRARIES
LOCAL_ADDITIONAL_JAVA_DIR

Droiddoc defines two new useful targets

mycomponent-docs
mycomponent-docs.zip

Skipping some content

If you are using the Android doclet you can make use of the @hide javadoc tag in your classes , methods or package.java
to hide classes and implementation from the javadoc documentation.

Sample makefile that is calling droiddoc

#
#
LOCAL_PATH := $(call my-dir)
# API documentation using the droiddoc doclet
# ============================================================
include $(CLEAR_VARS)

#
# Define a list of source files and AIDL files to document
LOCAL_SRC_FILES:= \
              $(call all-java-files-under, src)
              $(call all-Iaidl-files-under, src)

#
# If your source folder is not "src" you need to specify the
# AIDL includes directory separately. In this situation it is
# not necessary
#
# this module will be called gomo_api so if you want to generate the documentation
# use make gomo_api-docs
LOCAL_AIDL_INCLUDES:= src
LOCAL_MODULE:= gomo_api
LOCAL_MODULE_CLASS:= JAVA_LIBRARIES

LOCAL_DROIDDOC_OPTIONS:= \
                -offlinemode \
                -title "API documentation using droiddoc" \
                -hdf android.whichdoc offline \
                gomo.api

#
# Don't use the standard doclet so use the droiddoc doclet
#
LOCAL_DROIDDOC_USE_STANDARD_DOCLET:= false

#
# This directory can be empty but need to be present for Droidoc
# to generate the pacakge.html (bug?)
#
LOCAL_DROIDDOC_HTML_DIR:= docs/html

include $(BUILD_DROIDDOC)

Droiddoc doclet arguments

-templatedir <dir> point to the clearsilver template directory
-hdf <sdk.current> <preview>  replace a clearsiler variable?
-toroot <dir> use <dir> as root outdir
-htmldir <dir> the location where static html is found
-samplecode <in directory> <location> <description> 
-title <title> the document title
-werror set warnings are errors
-proofread <file>
-todo <file>
-public set show level to public
-protected set show level to protected
-package set show level to package
-private set show level to private
-hidden set showLevel to hidden
-stubs <dir> set the stubs directory to <dir>
-stubspackages <package1>:<package2> 
-sdkvalues <dir> set sdk value path???
-apixml <file> generate an XML API in file file
-nodocs do not generate documentation
-since <tag> <version>
-offlinemode set the documentation mode to offline.