JavaDocumentationImport.md

Java documentation import

Information sources

• Java sources - contains docs. Need javadoc tool to extract them
• Java stub sources - can extract API, does not contain documentation
• DroidDoc - docs as is. Impossible to predict format changes. Needs horrible hack (scraping). And changes occur quite often
• JavaDoc - docs as is. Third party libs could provide them. Format changes are predictable and not often, but matters and bites us. Needs horrible hack (scraping). They are often the only information sources.

Components where documentation matters

• Android framework stable API - sources are available (but often delayed), stubs are available, docs are not reliably available (DroidDoc, no docs component anymore)
• Android framework preview API - no sources, stubs are available, docs are horrible (DroidDoc).
• Android support components - sources are available, updates are very often.
• Google Play Services components - no sources, updates are very often, docs are horrible (Google's own doclet). Docs are technically proprietary and cannot be imported.
• Third-party libraries - only sources and standard Java doclets (6/7/8) can be supported.

What to do for documentation

• Android framework stable - export docs from sources. The exported docs should be Java8 (or Java9 if we switch).
• Android framework preview - no need to support. We can reuse stable API docs.
• Android support components - export docs from sources.
• Google Play Services - we can't do anything. Or someone write JavaDocScraper for it.
• Third-party libraries - only sources and standard Java doclets (6/7/8) can be supported.