search

prebid / prebid-mobile-android

Prebid Mobile SDK for Android applications
Apache License 2.0
58 stars 84 forks source link

Investigate creating API documentation for Android Prebid SDK #755

Open bretg opened 5 months ago

bretg commented 5 months ago

We would like to utilize javadocs in Prebid SDK, but running into a problem.

I read various sources for how to get started with javadocs, like https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html

In theory, it's easy, but javadoc is choking on imports:

% javadoc PrebidMobile/PrebidMobile-core/src/main/java/org/prebid/mobile/PrebidMobile.java Loading source file PrebidMobile/PrebidMobile-core/src/main/java/org/prebid/mobile/PrebidMobile.java... Constructing Javadoc information... PrebidMobile/PrebidMobile-core/src/main/java/org/prebid/mobile/PrebidMobile.java:19: error: package android.content does not exist import android.content.Context;

Searching around for a solution, looks like we might need to use a gradle task. Found that publisher.gradle already has a javadoc task, but trying that path results in an error:

% gradle javadoc … Unrecognized VM option 'MaxPermSize=2048M'

This might have to do with my local java environment, which is Corretto 17. (?)

The goal of this issue is to find if there's a way to build javadocs while ignoring import references.

Note that we need to do this from the command line in the long run because we're going to want to script the update of the documentation if it's going to be useful. i.e. I'm not as interested if there's an involved process of setting up an IDE that works. If the process of publishing API reference changes requires a lot of effort, it won't get done and the online docs will fall behind.