No Java Documentation

[jnbDeveloper]

New Feature

<- Description of the feature being requested and any outcomes desired, an example use case, and any suggestions for solution ->

Why

<- 1-2 sentence description of why you're requesting this feature. What problem does it solve? Why is it valuable? ->

[anox1337]

Hello jnbDeveloper, have you tried looking here:

Guide, Examples, API Reference.... https://docs.mapbox.com/android/maps/guides/

[audaciouscode]

Not having Java documentation is EXTREMELY customer hostile, given that there are a good number of us who have been building on Mapbox for the better part of a decade and have LARGE legacy code bases that we need to maintain.

Case in point - I just spent the better part of the past two hours trying and failing to figure out how to translate your Kotlin example for a circle annotation into the equivalent Java and failing. There are names and conventions used in the Kotlin code that have no Java equivalents that I could find, and it's pretty crappy of you to treat some of your oldest customers in this manner.

[jush]

@audaciouscode could you please share what specific "names and conventions used in the Kotlin code that have no Java equivalents that I could find" were challenging?

It would help us to identify possible improvements in our docs and/or codebase.

Thanks.

[audaciouscode]

In your first code sample on annotations, you have this code:

// Create an instance of the Annotation API and get the PointAnnotationManager.
val annotationApi = mapView?.annotations
val pointAnnotationManager = annotationApi?.createPointAnnotationManager(mapView)

In Java, I have the mapView object (so far, so good), but when I try to do the equivalent in Java, there is no annotations member on the mapView object, no getAnnotations() method or anything similar.

Instead, I had to go spelunking through the Mapbox codebase itself to discover the alternative that worked in Java:

AnnotationPlugin annotationApi = this.mMapView.getPlugin(Plugin.MAPBOX_ANNOTATION_PLUGIN_ID);

AnnotationConfig config = new AnnotationConfig();

PointAnnotationManager pointsManager = (PointAnnotationManager) annotationApi.createAnnotationManager(AnnotationType.PointAnnotation, config);

Similarly with gestures, you have the following Kotlin code to disable the pitch controls:

mapView.gestures.pitchEnabled = false

Whereas in Java (after more code archeology), I had to write:

GesturesPlugin gestures = GesturesUtils.getGestures(this.mMapView);
gestures.setPitchEnabled(false);

The current Mapbox documentation is riddled with issues and omissions like these, to the point that the documentation (for us Java programmers supporting LARGE legacy codebases) is really only good for seeing if something is possible in the latest API, and it's a crapshoot to see if we can figure out the mystery classes and calls we need to make by inspecting the codebase itself.

I don't have time to exhaustively iterate over ALL of the places that this is an issue, but for every snippet of Kotlin that you show how to do something, you EXPLICITLY need to include the Java equivalent, given that the names and method calls in Kotlin only occasionally map to what a normal programmer would expect to see in Java.

[jush]

Thanks @audaciouscode for coming back with concrete examples.

I agree that Kotlin extensions functions are not friendly for Java consumption.

One trick is to look at the imports, that will give a hint where the extension function could be. Unfortunately, in order to keep the examples brief we do not add the imports. For example this one would have lead you to AnnotationExt.kt which then it is easy to translate to Java AnnotationsUtils.getAnnotations(mapView);.

Another trick I used in the past is to create a simple Android app in Kotlin and dump there the Mapbox example code and then explore it before converting to Java.

[audaciouscode]

@jush: Or, you could document how to do these things in Java. Many other companies do it (see below), and it helps make their customers' lives better.

Each minute I spend reverse-engineering your code to try to achieve something that was pretty simple (and documented) in prior releases, is a minute I'm not doing useful work for my clients, which is how I get paid, and how I pay Mapbox in the end.

If brevity in your code documentation is much more important than revenue from paying customers, just be up-front with that, and I can start looking for alternative mapping providers, either defaulting back to the platform-provided Google and Apple APIs or seeking out an alternative such as Radar, who DOES provide documentation in both languages.