Merge pull request sockeqwe#122 from sockeqwe/presenterJavaDoc

JavaDoc update for MvpBasePresenter

mvp-common/src/main/java/com/hannesdorfmann/mosby/mvp/MvpBasePresenter.java

@@ -27,6 +27,41 @@
  * presenter before calling {@link #getView()} to access the view.
  * </p>
  *
+ * <p>
+ * <b>Why is this class using internally a WeakReference for referring to the attached view and why
+ * do I have to use {@link #isViewAttached()} check?</b>
+ * </p>
+ * <p>
+ * In a "perfect world" you wouldn't need this check nor a WeakReference. In Mosby <b>all
+ * interaction
+ * from Presenter to View must be executed on android's main UI thread</b>. Since screen
+ * orientation changes are also executed on the main UI thread it is not possible to run into the
+ * scenario where view is detached while presenter still wants to update the UI, right? However, we
+ * are not living in a perfect world. Let's say you use an AsyncTask to make an http request and
+ * the Presenter gets the result back and updates the View. If you forget to cancel this AsyncTask
+ * after the View has been destroyed (i.e. android back button pressed, {@link
+ * MvpPresenter#detachView(boolean)} will be called) then you can run into the scenario that the
+ * View is detached from Presenter and then the Presenter gets the result back from AsyncTask and
+ * wants to update the View which is null (because detached). So the `isViewAttached()` check is
+ * basically some kind of safety net. In a perfect implementation you wouldn't need the {@link
+ * #isViewAttached()} check.
+ * </p>
+ * <p>
+ * Furthermore, in a perfect world you wouldn't need a WeakReference for referring to the View. In
+ * Mosby you can create your own MvpDelegate to change Mosby's default implementation and
+ * behaviour.
+ * We have decided to use a WeakReference to avoid memory leaks if you use a custom MvpDelegate
+ * that is not implementing the contract of attaching and detaching View from Presenter
+ * properly (i.e. don't detach view in Activity.onDestroy() ).
+ * </p>
+ * <p>
+ * So using a WeakReference and adding the {@link #isViewAttached()} check are basically just some
+ * kind of safety net and not needed in a "perfect world". Please note that if you are sure that
+ * you are coding in such a "perfect world" then you can also think about implementing your own
+ * Presenterentirely without WeakReference and isViewAttached(). Note also that
+ * {@link MvpPresenter} is an interface. Hence implementing you own Presenter is easy.
+ * </p>
+ *
  * @param <V> type of the {@link MvpView}
  * @author Hannes Dorfmann
  * @see MvpNullObjectBasePresenter

mvp-common/src/main/java/com/hannesdorfmann/mosby/mvp/MvpPresenter.java

@@ -17,7 +17,12 @@
 package com.hannesdorfmann.mosby.mvp;
 
 /**
- * The base interface for each mvp presenter
+ * The base interface for each mvp presenter.
+ *
+ * <p>
+ * Mosby assumes that all interaction (i.e. updating the View) between Presenter and View is
+ * executed on android's main UI thread.
+ * </p>
  *
  * @author Hannes Dorfmann
  * @since 1.0.0