Skip to content

Commit

Permalink
Add some docstrings (quran#1288)
Browse files Browse the repository at this point in the history
  • Loading branch information
ismail-s authored Mar 1, 2020
1 parent 35cbb2d commit 357b493
Show file tree
Hide file tree
Showing 9 changed files with 69 additions and 0 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,17 @@
import io.reactivex.disposables.Disposable;
import timber.log.Timber;

/**
* Launch {@link QuranActivity} after performing the following checks:
* <ul>
* <li>Check that we have permission to write to external storage (if we need this permission)
* and if not, ask the user for permission</li>
* <li>Verify that we have the necessary Quran data downloaded on the device</li>
* </ul>
* The logic is split between {@link QuranDataActivity} and {@link QuranDataPresenter},
* and {@link QuranDownloadService} is (mostly) used to perform the actual downloading of
* any Quran data.
*/
public class QuranDataActivity extends Activity implements
DefaultDownloadReceiver.SimpleDownloadListener,
ActivityCompat.OnRequestPermissionsResultCallback {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,10 @@

import com.quran.labs.androidquran.ui.QuranActivity;

/**
* Handle shortcuts by lauching the appropriate activity.
* Currently, there is only one shortcut to go to the last page.
*/
public class ShortcutsActivity extends AppCompatActivity {
public static final String ACTION_JUMP_TO_LATEST = "com.quran.labs.androidquran.last_page";

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,14 @@
import static com.quran.labs.androidquran.ui.helpers.SlidingPagerAdapter.TRANSLATION_PAGE;
import static com.quran.labs.androidquran.widgets.AyahToolBar.AyahToolBarPosition;

/**
* Activity that displays the Quran (in Arabic or translation mode).
* <p>
* Essentially, this activity consists of a {@link ViewPager} of Quran pages
* (using {@link QuranPageAdapter}).
* {@link AudioService} is used to handle playing audio, and this is synced with the display of
* the Quran.
*/
public class PagerActivity extends QuranActionBarActivity implements
AudioStatusBar.AudioBarListener,
DefaultDownloadReceiver.DownloadListener,
Expand Down
14 changes: 14 additions & 0 deletions app/src/main/java/com/quran/labs/androidquran/ui/QuranActivity.kt
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,20 @@ import java.util.concurrent.TimeUnit.MILLISECONDS
import javax.inject.Inject
import kotlin.math.abs

/**
* The home screen activity for the app. Displays a toolbar and 3 fragments:
*
* * [SuraListFragment]
* * [JuzListFragment]
* * [BookmarksFragment]
*
* When this activity is created, it may run a background check to see if updated translations
* are available, and if so, show a dialog asking the user if they want to download them.
*
* This activity is called from several places:
* * [com.quran.labs.androidquran.QuranDataActivity]
* * [ShortcutsActivity]
*/
class QuranActivity : QuranActionBarActivity(),
OnBookmarkTagsUpdateListener,
JumpDestination {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,12 @@

import static com.quran.labs.androidquran.data.Constants.JUZ2_COUNT;

/**
* Fragment that displays a list of all Juz (using {@link QuranListAdapter}, each divided into
* 8 parts (with headings for each Juz).
* When a Juz part is selected (or a Juz heading), {@link QuranActivity#jumpTo(int)} is called to
* jump to that page.
*/
public class JuzListFragment extends Fragment {
private static int[] sEntryTypes = {
JuzView.TYPE_JUZ, JuzView.TYPE_QUARTER,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,12 @@
import static com.quran.labs.androidquran.data.Constants.JUZ2_COUNT;
import static com.quran.labs.androidquran.data.Constants.SURAS_COUNT;

/**
* Fragment that displays a list of all Surahs (using {@link QuranListAdapter}, with headings
* indicating which Juz a Sura starts in.
* When a Sura is selected (or a Juz heading), {@link QuranActivity#jumpTo(int)} is called to jump
* to that page.
*/
public class SuraListFragment extends Fragment {

private RecyclerView mRecyclerView;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,12 @@
import com.quran.labs.androidquran.ui.util.PageController;
import com.quran.labs.androidquran.util.QuranSettings;

/**
* Layout class for a single Arabic page of the Quran, with margins/background.
* <p>
* Note that the image of the Quran page to be displayed is set by users of this class by calling
* {@link #getImageView()} and calling the appropriate methods on that view.
*/
public class QuranImagePageLayout extends QuranPageLayout {
private HighlightingImageView imageView;

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,15 @@
import com.quran.labs.androidquran.ui.util.PageController;
import com.quran.labs.androidquran.util.QuranSettings;

/**
* Generic layout class for a single page of the Quran.
* <p>
* The actual contents of the page are determined by the subclass, which specifies the view to
* display with {@link #generateContentView(Context, boolean)}. If the device is landscape and
* {@link #shouldWrapWithScrollView()} returns true, then the view is wrapped with an
* {@link ObservableScrollView}. Margins get displayed around the page, along with an appropriate
* background.
*/
public abstract class QuranPageLayout extends QuranPageWrapperLayout
implements ObservableScrollView.OnScrollListener {

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,11 @@
import com.quran.labs.androidquran.R;
import com.quran.labs.androidquran.util.QuranSettings;

/**
* Wrapper around {@link ViewGroup} that adds {@link #showError(int)} and {@link #hideError()}
* methods. These methods display/hide a given error message and a retry button.
* When the retry button is clicked, {@link #handleRetryClicked} is called.
*/
public abstract class QuranPageWrapperLayout extends ViewGroup {

private View errorLayout;
Expand Down

0 comments on commit 357b493

Please sign in to comment.