I'm now using Gradle for all my projects, and even for javadoc generation.
android.libraryVariants.all { variant ->
task("generate${variant.name}Javadoc", type: Javadoc) {
title = "$name $version API"
source = variant.javaCompile.source
ext.androidJar = "${android.plugin.sdkDirectory}/platforms/${android.compileSdkVersion}/android.jar"
ext.googlePlayServicesJar = "${android.plugin.sdkDirectory}/extras/google/google_play_services/libproject/google-play-services_lib/libs/google-play-services.jar"
classpath = files(variant.javaCompile.classpath.files, ext.androidJar, ext.googlePlayServicesJar)
options.links("http://docs.oracle.com/javase/7/docs/api/");
options.links("http://d.android.com/reference/");
//options.linksOffline("http://d.android.com/reference", "${android.plugin.sdkDirectory}/docs/reference");
exclude '**/BuildConfig.java'
exclude '**/R.java'
}
}
With that code I got everything working, except one thing: regular Android API objects like Activity, Bitmap etc.
Java's links are working fine.
The final generated documentation does not link to http://d.android.com/reference.
I tried both options.links() and options.linksOffline() without success.
EDIT
Thanks to #ejb, the problem was that you cannot provide multiple options.links() at the same time.
So I used both options.links() for Java's documentation and options.linksOffline() for Android's documentation:
options {
links("http://docs.oracle.com/javase/7/docs/api/");
linksOffline("http://d.android.com/reference", "${android.plugin.sdkDirectory}/docs/reference");
//stylesheetFile = new File(projectDir, "stylesheet.css");
}
I was able to successfully link to http://d.android.com/reference using the following snippet which is functionally exactly what you have (as far as I can tell).
android.libraryVariants.all { variant ->
task("generate${variant.name.capitalize()}Javadoc", type: Javadoc) {
// title = ''
// description = ''
source = variant.javaCompile.source
classpath = files(variant.javaCompile.classpath.files, project.android.getBootClasspath())
options {
links "http://docs.oracle.com/javase/7/docs/api/"
linksOffline "http://d.android.com/reference","${android.sdkDirectory}/docs/reference"
}
exclude '**/BuildConfig.java'
exclude '**/R.java'
}
}
So there is something else amiss here.
You have to build the javadoc offline, as it doesn't seem the package-list is available on the path of the web service. Maybe double check that you actually have the docs loaded locally, and make sure there is a package-list in the /[android-sdk]/docs/reference directory.
If you still can't figure it out, perhaps you could post output.
Another thing you might check is the ./build/tmp/[taskname]/javadoc.options, the head of said file should show the appropriate options carefully set. Things to check for would include the proper inclusion of the android.jar in the -classpath and the presence of linksOffline with expected arguments: -linksoffline extDocURL packageListLoc
javadoc.options should have both options with only the respective arguments:
-linksoffline 'http://d.android.come/reference' '[sdkDir]/docs/reference'
-links 'http://docs.oracle.com/javase/7/docs/api/'
EDIT: android.getBootClasspath() is nicer, thanks to P-chan.
For Android Gradle plugin 1.1.2+ (com.android.tools.build:gradle:1.1.+)
libraryVariants - does not work anymore
use:
task javadoc(type: Javadoc) {
source = android.sourceSets.main.java.srcDirs
classpath += project.files(android.getBootClasspath().join(File.pathSeparator))
destinationDir = file("../javadoc/")
failOnError false
}
destinationDir = file("../javadoc/") - locate javadocs at root of project directory (in this way jenkins javadoc plugin could find it and show in special Document panel)
failOnError false - for suppress warnings that can cause fail build on jenkins
Alternative for Gradle JavaDocs
Doxygen - cross reference documentation tool.
could be run from UI or terminal: http://www.doxygen.nl/manual/doxygen_usage.html
Generating javadoc available throw java tool: 'javadoc'
run from command line:
javadoc -d docs -sourcepath app/src/main/java -subpackages com
docs - destination folder
Related
Generating the javadoc worked perfectly fine with Java 8 but does not work with the newly bundled Java 11 in Android Studio.
I get errors like error: package ... does not exist or error: cannot find symbol, but these are all files and references that should not be public or documented in any case.
As additional info: I am working on an SDK (thats why some classes need to be not documented) and here is the task that creates the javadoc.
I would appreciate any help on this matter.
And yes I read this post: javadoc: "package [...] does not exist" for external references without docs but it is not applicable, since the files that are causing the issue are not third party.
task("generate${variant.name.capitalize()}Javadoc", type: Javadoc) {
options.memberLevel = JavadocMemberLevel.PUBLIC
options.encoding = "utf-8"
failOnError = false
source = variant.javaCompiler.source
def androidJar = "${android.sdkDirectory}/platforms/${android.compileSdkVersion}/android.jar"
doFirst {
classpath = files(variant.javaCompile.classpath.files) + files(androidJar)
}
options {
links "http://docs.oracle.com/javase/7/docs/api/"
linksOffline "http://d.android.com/reference", "${android.sdkDirectory}/docs/reference"
}
// and then there are includes of packages and files
}
Edit:
When removing the includes the javadoc is created without an issue, but of course for all the classes.
Edit 2:
Found an interim solution by ignoring source errors.
options.addStringOption('-ignore-source-errors', '-quiet')
I'm using Dokka v0.9.17 for Android. When I run ./gradlew dokka it generates the docs but it include so many packages that I don't care about like android.support.fragment and packages for all the third party libraries. How can I tell Dokka to only generate doc for my code?
How can I remove Dagger _Factory files from the doc?
My configuration is like this
dokka {
moduleName = 'app'
outputFormat = 'html'
outputDirectory = "$buildDir/javadoc"
includeNonPublic = true
skipEmptyPackages = true
noStdlibLink = true
}
Paragones had the correct answer to a different so issue
https://github.com/Kotlin/dokka/issues/258
namely you need to add this task and modify it to only delete the stuff you want deleted:
task deleteUnusedDokkaAssets(type: Delete) {
file("$rootDir/docs").listFiles().each {
if(it.name.contains("android.R")) project.delete it
if(it.name.contains("android.support")) project.delete it
if(it.name.contains("com.google")) project.delete it
if(it.name.contains("com.crashlytics")) project.delete it
}
}
note you will not need the android.R line with the updated version of dokka
I am trying to use Dokka plugin to generate Javadoc for android Kotlin application. I added the plugin to my gradle:
classpath "org.jetbrains.dokka:dokka-gradle-plugin:0.9.15"
Then I made a basic configuration following project instructions:
dokka {
outputFormat = 'javadoc'
outputDirectory = "$rootDir/docs"
skipEmptyPackages = true
noStdlibLink = true
}
I generate documentation using basic gradle command:
[user#linux AppDir]$ bash gradlew dokka
Output is fine, but it includes multiple directories from android or plugins I have added to my project, for example:
android.R
android.support
com.google
com.crashlytics
.
.
.
etc.
How do I skip these packages? Is there any way to generate dock only for my /app/scr/java folder, and files I created? Any help is appreciated.
Dokka version 0.9.16 will include a bugfix to remove generated files from documentation.
In version 0.9.15, the following commit seemed to address that "Suppress output of android.R and other generated stuff in dokka-android", but apparently after creating the suppresedFiles map with the needed information, it was not really used to filter sourceSets.
UPDATE: Dokka 0.9.16 has been released with the fix, among other improvements.
#224 Filtered out Android generated classes from docs
Here is a working example with Dokka 0.9.16:
task dokka(overwrite: true, type: org.jetbrains.dokka.gradle.DokkaAndroidTask) {
outputFormat = 'javadoc'
outputDirectory = "$buildDir/docs"
// Do not create index pages for empty packages
skipEmptyPackages = true
//Do not output deprecated members. Applies globally, can be overridden by packageOptions
skipDeprecated = false
//No default documentation link to kotlin-stdlib
noStdlibLink = false
}
If you use Android then the type is important: org.jetbrains.dokka.gradle.DokkaAndroidTask
Not DokkaTask but DokkaAndroidTask.
I’m trying to upload my Library project to jCenter.
when I run gradlew install I’m getting the error:
Execution failed for task ':myLibraryProject:javadoc'
I added the code below to my library project:
task androidJavadocs(type: Javadoc) {
failOnError false // add this line
source = android.sourceSets.main.java.getSrcDirs()
}
but still I get
"Javadoc generation failed. Generated Javadoc options file..."
I've also tried the accepted answer from here: Generate JavaDocs with Android Gradle plugin
Can I disable the generation of Javadocs, or maybe try to continue with the build although the failure?
Add these lines to your module build.gradle
tasks.withType(Javadoc) {
failOnError false
options.addStringOption('Xdoclint:none', '-quiet')
options.addStringOption('encoding', 'UTF-8')
options.addStringOption('charSet', 'UTF-8')
}
Or you can add these:
android.libraryVariants.findAll { variant -> variant.name == 'Release' } each { variant ->
task("generate${variant.name}Javadoc", type: Javadoc) {
description "Generates Javadoc for $variant.name."
source = variant.javaCompile.source
ext.androidJar = "${android.plugin.sdkDirectory}/platforms/${android.compileSdkVersion}/android.jar"
classpath = files(variant.javaCompile.classpath.files) + files(ext.androidJar)
}
task("bundle${variant.name}Javadoc", type: Zip) {
description "Bundles Javadoc into zip for $variant.name."
classifier = "javadoc"
from tasks["generate${variant.name}Javadoc"]
}
I don't recommend disabling JavaDoc generation. Instead, try just running
./gradlew javadoc
This should give you detailed log output about the warnings and errors that are occurring. Fixing these errors should prevent JavaDoc from causing the failure.
In our case, the problem was that we had to remove .gitignore files. They were listed in the file javadoc.options. After that, the task finished successfully.
Run your app without --deviceID. Just run npx react-native run-android . It works for me.
I am building JavaDoc for an API wherein classes in the API depend on R.java. I want to build the Javadoc w/o symbol errors referencing the missing R.java file as even when I set failOnError false the build succeeds but our Jenkins job will report the build as Failed when errors occur in successful builds. The task below will successfully create the javadocs but will report errors during build relating to not finding R.java.
android.libraryVariants.all { variant ->
def name = variant.name.capitalize()
task("generate${name}Doclava", type: Javadoc) {
description "Generates Javadoc for $variant.name."
source = variant.javaCompile.source
title = null
// use android.bootClasspath instead of building our own path to android jar
//ext.androidJar = "${android.sdkDirectory}/platforms/${android.compileSdkVersion}/android.jar"
// hardcoded path to generated R.java file to avoid javadoc compile issues
ext.R = "build/generated/source/r/minSDK15/release"
classpath += project.files(android.sourceSets.main.java.srcDirs, variant.javaCompile.classpath.files, android.bootClasspath)
destinationDir = file("${project.docsDir}/${name}/doclava")
options {
docletpath = configurations.jaxDoclet.files.asType(List)
doclet "com.google.doclava.Doclava"
bootClasspath new File(System.getenv('JAVA_HOME') + "/jre/lib/rt.jar")
addStringOption "XDignore.symbol.file", "-quiet"
addStringOption "hdf project.name", "${project.name}"
addStringOption "federate android", "http://d.android.com/reference"
addStringOption "federationxml android", "http://doclava.googlecode.com/svn/static/api/android-10.xml"
addStringOption "federate JDK", "http://download.oracle.com/javase/6/docs/api/index.html?"
addStringOption "federationxml JDK", "http://doclava.googlecode.com/svn/static/api/openjdk-6.xml"
addStringOption "templatedir", "${project.docsDir}/${name}/doclava/templates"
addStringOption "apixml", "${project.docsDir}/${name}/doclava/api-${project.version}.xml"
addStringOption "since doclava/since/api-1.0.0.xml", "1.0.0"
addStringOption "apiversion", "${project.version}"
failOnError false
}
// exclude generated files
exclude '**/BuildConfig.java'
exclude '**/R.java'
// exclude internal packages
exclude '**/internal/**'
options.addStringOption "apixml", "${project.docsDir}/${name}/doclava/api-${project.version}.xml"
}
}
Some things I have tried:
Hardcode the path to the generated R.java file and add to the classpath.
classpath += project.files(android.sourceSets.main.java.srcDirs, variant.javaCompile.classpath.files, android.bootClasspath, ext.R)
This successfully removes the errors so the build succeeds, but the resulting javadoc has empty links to R.*.class in the javadoc.
Remove the exclude '**/R.java' line from the exclude list along with not including the path to R.java in the classpath.
This successfully removes the errors and the build succeeds, but the resulting javadoc has links to R.*.class files.
It seems the exclude statement is excluding from the classpath and not the javadoc. Any insight into how to generate a javadoc where classes depend on R.java but don't include R.java in the javadoc output would be deeply appreciated.
On Android Studio, go to the following settings (settings can be accessed via File > Settings):
Appearance & Behaviour > Scopes
You should be able to browse your project files here. Now select your files and use the buttons on the far right to include/exclude them to your scope (you can exclude, or not include R.java files and BuildConfig.java files). Make sure the checkbox at the bottom "Share scope" is ticked, and your scope has a memorable name.
Next go to the Javadoc generator dialog (Tools > Generate Javadoc). Select the bottom radio button ("Custom Scope") and then from the menu, select the scope you created earlier. There are other settings you can configure for your Javadocs.
Finally click 'OK', and you should have generated Javadocs.
Hopefully this should solve your problem.
I suspect you are trying to exclude R.java because the auto-generated javadoc in that class doesn't conform to doclint. So you are seeing a bunch of errors and warnings like:
R.java:530: error: unknown tag: colgroup
* <colgroup align="left" />
^
What about removing the exclude '**/R.java' and suppressing any errors generated by R.java instead?
Using this as a basis, and then looking at Xdoclint documentation, you should be able suppress R.java errors by adding:
options.addStringOption('Xdoclint:none R.java', '-quiet')
I have tested this and it removes the R.java errors. You'll still see them print to console, but it won't count in the final error numbers.