Improve documentation for map events

[zugaldia]

We currently provide one line descriptions for map events inside Javadoc, but sometimes it isn't completely clear how events are different from each other, or what's expected for developers to be able to do in response to a specific event.

For example, for WILL_START_RENDERING_FRAME we currently say:

This event is triggered when the map will start rendering a frame.

iOS explains this further on mapViewWillStartRenderingFrame:

Tells the delegate that the map view is about to redraw.

This method is called any time the map view needs to redraw due to a change in the viewpoint or style property transition. This method may be called very frequently, even moreso than -mapViewRegionIsChanging:. Therefore, your implementation of this method should be as lightweight as possible to avoid affecting performance.

We should clarify our current Javadoc and provide some more background on map events. Current iOS docs (here, here) are a great starting point for this.

cc: @langsmith @cammace

[tobrun]

FWIW: the core names sometimes make it a bit more clear what these events actually mean.
You can find them in map_observer.hpp, though they're undocumented.

    virtual void onCameraWillChange(CameraChangeMode) {}
    virtual void onCameraIsChanging() {}
    virtual void onCameraDidChange(CameraChangeMode) {}
    virtual void onWillStartLoadingMap() {}
    virtual void onDidFinishLoadingMap() {}
    virtual void onDidFailLoadingMap(std::exception_ptr) {}
    virtual void onWillStartRenderingFrame() {}
    virtual void onDidFinishRenderingFrame(RenderMode) {}
    virtual void onWillStartRenderingMap() {}
    virtual void onDidFinishRenderingMap(RenderMode) {}
    virtual void onDidFinishLoadingStyle() {}
    virtual void onSourceChanged(style::Source&) {}

When implementing #8389, I'm thinking of changing the name of our public API to match the one exposed by core. AFAIK the naming as-is, was mostly copied from iOS which matches Mapkit.

[zugaldia]

When implementing #8389, I'm thinking of changing the name of our public API to match the one exposed by core. AFAIK the naming as-is, was mostly copied from iOS which matches Mapkit.

👍 Agreed that matching core's naming makes more sense here than matching MapKit's.

[tobrun]

With #9498 we are introducing dedicated callbacks that will match the core api fully in terms of naming. All these callbacks with be accompanied with javadoc.