diff --git a/app/src/main/java/com/keylesspalace/tusky/util/CountUpDownLatch.java b/app/src/main/java/com/keylesspalace/tusky/util/CountUpDownLatch.java index 5791cf60..6874337b 100644 --- a/app/src/main/java/com/keylesspalace/tusky/util/CountUpDownLatch.java +++ b/app/src/main/java/com/keylesspalace/tusky/util/CountUpDownLatch.java @@ -15,6 +15,13 @@ package com.keylesspalace.tusky.util; +/** + * This is a synchronization primitive related to {@link java.util.concurrent.CountDownLatch} + * except that it starts at zero and can count upward. + *

+ * The intended use case is for waiting for all tasks to be finished when the number of tasks isn't + * known ahead of time, or may change while waiting. + */ public class CountUpDownLatch { private int count; diff --git a/app/src/main/java/com/keylesspalace/tusky/util/DateUtils.java b/app/src/main/java/com/keylesspalace/tusky/util/DateUtils.java index beb58ef9..3d32d08a 100644 --- a/app/src/main/java/com/keylesspalace/tusky/util/DateUtils.java +++ b/app/src/main/java/com/keylesspalace/tusky/util/DateUtils.java @@ -20,8 +20,10 @@ import android.content.Context; import com.keylesspalace.tusky.R; public class DateUtils { - /* This is a rough duplicate of android.text.format.DateUtils.getRelativeTimeSpanString, - * but even with the FORMAT_ABBREV_RELATIVE flag it wasn't abbreviating enough. */ + /** + * This is a rough duplicate of {@link android.text.format.DateUtils#getRelativeTimeSpanString}, + * but even with the FORMAT_ABBREV_RELATIVE flag it wasn't abbreviating enough. + */ public static String getRelativeTimeSpanString(Context context, long then, long now) { final long MINUTE = 60; final long HOUR = 60 * MINUTE; diff --git a/app/src/main/java/com/keylesspalace/tusky/util/DownsizeImageTask.java b/app/src/main/java/com/keylesspalace/tusky/util/DownsizeImageTask.java index fe222a70..c9df6a19 100644 --- a/app/src/main/java/com/keylesspalace/tusky/util/DownsizeImageTask.java +++ b/app/src/main/java/com/keylesspalace/tusky/util/DownsizeImageTask.java @@ -32,6 +32,10 @@ import java.io.InputStream; import java.util.ArrayList; import java.util.List; +/** + * Reduces the file size of images to fit under a given limit by resizing them, maintaining both + * aspect ratio and orientation. + */ public class DownsizeImageTask extends AsyncTask { private static final String TAG = "DownsizeImageTask"; private int sizeLimit; @@ -39,6 +43,11 @@ public class DownsizeImageTask extends AsyncTask { private Listener listener; private List resultList; + /** + * @param sizeLimit the maximum number of bytes each image can take + * @param contentResolver to resolve the specified images' URIs + * @param listener to whom the results are given + */ public DownsizeImageTask(int sizeLimit, ContentResolver contentResolver, Listener listener) { this.sizeLimit = sizeLimit; this.contentResolver = contentResolver; @@ -223,6 +232,7 @@ public class DownsizeImageTask extends AsyncTask { super.onPostExecute(successful); } + /** Used to communicate the results of the task. */ public interface Listener { void onSuccess(List contentList); void onFailure(); diff --git a/app/src/main/java/com/keylesspalace/tusky/util/HttpHeaderLink.java b/app/src/main/java/com/keylesspalace/tusky/util/HttpHeaderLink.java index 0fccdcbf..fe0b257f 100644 --- a/app/src/main/java/com/keylesspalace/tusky/util/HttpHeaderLink.java +++ b/app/src/main/java/com/keylesspalace/tusky/util/HttpHeaderLink.java @@ -15,6 +15,11 @@ import android.support.annotation.Nullable; import java.util.ArrayList; import java.util.List; +/** + * Represents one link and its parameters from the link header of an HTTP message. + * + * @see RFC5988 + */ public class HttpHeaderLink { private static class Parameter { public String name; @@ -114,6 +119,10 @@ public class HttpHeaderLink { return -1; } + /** + * @param line the entire link header, not including the initial "Link:" + * @return all links found in the header + */ public static List parse(@Nullable String line) { List linkList = new ArrayList<>(); if (line != null) { @@ -133,6 +142,11 @@ public class HttpHeaderLink { return linkList; } + /** + * @param links intended to be those returned by parse() + * @param relationType of the parameter "rel", commonly "next" or "prev" + * @return the link matching the given relation type + */ @Nullable public static HttpHeaderLink findByRelationType(List links, String relationType) { diff --git a/app/src/main/java/com/keylesspalace/tusky/util/LinkHelper.java b/app/src/main/java/com/keylesspalace/tusky/util/LinkHelper.java index b1f31f6a..ab1ad6aa 100644 --- a/app/src/main/java/com/keylesspalace/tusky/util/LinkHelper.java +++ b/app/src/main/java/com/keylesspalace/tusky/util/LinkHelper.java @@ -46,6 +46,16 @@ public class LinkHelper { } } + /** + * Finds links, mentions, and hashtags in a piece of text and makes them clickable, associating + * them with callbacks to notify when they're clicked. + * + * @param view the returned text will be put in + * @param content containing text with mentions, links, or hashtags + * @param mentions any '@' mentions which are known to be in the content + * @param useCustomTabs whether to use custom tabs when opening web links + * @param listener to notify about particular spans that are clicked + */ public static void setClickableText(TextView view, Spanned content, @Nullable Status.Mention[] mentions, boolean useCustomTabs, final LinkListener listener) { diff --git a/app/src/main/java/com/keylesspalace/tusky/util/MediaUtils.java b/app/src/main/java/com/keylesspalace/tusky/util/MediaUtils.java index 9265aadf..47e38904 100644 --- a/app/src/main/java/com/keylesspalace/tusky/util/MediaUtils.java +++ b/app/src/main/java/com/keylesspalace/tusky/util/MediaUtils.java @@ -43,6 +43,10 @@ import java.io.InputStream; public class MediaUtils { public static final int MEDIA_SIZE_UNKNOWN = -1; + /** + * Copies the entire contents of the given stream into a byte array and returns it. Beware of + * OutOfMemoryError for streams of unknown size. + */ @Nullable public static byte[] inputStreamGetBytes(InputStream stream) { ByteArrayOutputStream buffer = new ByteArrayOutputStream(); @@ -59,6 +63,12 @@ public class MediaUtils { return buffer.toByteArray(); } + /** + * Fetches the size of the media represented by the given URI, assuming it is openable and + * the ContentResolver is able to resolve it. + * + * @return the size of the media or {@link MediaUtils#MEDIA_SIZE_UNKNOWN} + */ public static long getMediaSize(ContentResolver contentResolver, Uri uri) { long mediaSize; Cursor cursor = contentResolver.query(uri, null, null, null, null); @@ -73,7 +83,7 @@ public class MediaUtils { return mediaSize; } - // Download an image with picasso + /** Download an image with picasso asynchronously and call the given listener when completed. */ public static Target picassoImageTarget(final Context context, final MediaListener mediaListener) { final String imageName = "temp"; return new Target() { diff --git a/app/src/main/java/com/keylesspalace/tusky/util/NotificationMaker.java b/app/src/main/java/com/keylesspalace/tusky/util/NotificationMaker.java index 5232cd6f..04f27e62 100644 --- a/app/src/main/java/com/keylesspalace/tusky/util/NotificationMaker.java +++ b/app/src/main/java/com/keylesspalace/tusky/util/NotificationMaker.java @@ -42,9 +42,16 @@ import org.json.JSONArray; import org.json.JSONException; public class NotificationMaker { - public static final String TAG = "NotificationMaker"; + /** + * Takes a given Mastodon notification and either creates a new Android notification or updates + * the state of the existing notification to reflect the new interaction. + * + * @param context to access application preferences and services + * @param notifyId an arbitrary number to reference this notification for any future action + * @param body a new Mastodon notification + */ public static void make(final Context context, final int notifyId, Notification body) { final SharedPreferences preferences = PreferenceManager.getDefaultSharedPreferences(context); diff --git a/app/src/main/java/com/keylesspalace/tusky/util/OkHttpUtils.java b/app/src/main/java/com/keylesspalace/tusky/util/OkHttpUtils.java index 577af8cf..bb71127b 100644 --- a/app/src/main/java/com/keylesspalace/tusky/util/OkHttpUtils.java +++ b/app/src/main/java/com/keylesspalace/tusky/util/OkHttpUtils.java @@ -46,18 +46,18 @@ import okhttp3.Request; import okhttp3.Response; public class OkHttpUtils { - static final String TAG = "OkHttpUtils"; // logging tag + private static final String TAG = "OkHttpUtils"; // logging tag /** * Makes a Builder with the maximum range of TLS versions and cipher suites enabled. - * + *

* It first tries the "approved" list of cipher suites given in OkHttp (the default in * ConnectionSpec.MODERN_TLS) and if that doesn't work falls back to the set of ALL enabled, * then falls back to plain http. - * + *

* API level 24 has a regression in elliptic curves where it only supports secp256r1, so this * first tries a fallback without elliptic curves at all, and then tries them after. - * + *

* TLS 1.1 and 1.2 have to be manually enabled on API levels 16-20. */ @NonNull @@ -104,7 +104,6 @@ public class OkHttpUtils { }; } - /** * Android version Nougat has a regression where elliptic curve cipher suites are supported, but * only the curve secp256r1 is allowed. So, first it's best to just disable all elliptic diff --git a/app/src/main/java/com/keylesspalace/tusky/util/ParserUtils.java b/app/src/main/java/com/keylesspalace/tusky/util/ParserUtils.java index da35a8f4..b0072ee9 100644 --- a/app/src/main/java/com/keylesspalace/tusky/util/ParserUtils.java +++ b/app/src/main/java/com/keylesspalace/tusky/util/ParserUtils.java @@ -19,7 +19,7 @@ import java.util.List; import static com.keylesspalace.tusky.util.StringUtils.QUOTE; /** - * Inspect and Get the information from an URL + * Inspect and get the information from a URL. */ public class ParserUtils { private static final String TAG = "ParserUtils"; @@ -56,7 +56,7 @@ public class ParserUtils { clipboard.setPrimaryClip(clip); } - // parse the HTML page + /** parse the HTML page */ private HeaderInfo parsePageHeaderInfo(String urlStr) throws Exception { Connection con = Jsoup.connect(urlStr); HeaderInfo headerInfo = new HeaderInfo(); diff --git a/app/src/main/java/com/keylesspalace/tusky/util/SpanUtils.java b/app/src/main/java/com/keylesspalace/tusky/util/SpanUtils.java index f2270117..e5697d5c 100644 --- a/app/src/main/java/com/keylesspalace/tusky/util/SpanUtils.java +++ b/app/src/main/java/com/keylesspalace/tusky/util/SpanUtils.java @@ -23,8 +23,16 @@ import java.util.regex.Matcher; import java.util.regex.Pattern; public class SpanUtils { + /** + * @see + * Tag#HASHTAG_RE. + */ private static final String TAG_REGEX = "(?:^|[^/)\\w])#([\\w_]*[\\p{Alpha}_][\\w_]*)"; private static Pattern TAG_PATTERN = Pattern.compile(TAG_REGEX, Pattern.CASE_INSENSITIVE); + /** + * @see + * Account#MENTION_RE + */ private static final String MENTION_REGEX = "(?:^|[^/[:word:]])@([a-z0-9_]+(?:@[a-z0-9\\.\\-]+[a-z0-9]+)?)"; private static Pattern MENTION_PATTERN = @@ -98,6 +106,7 @@ public class SpanUtils { } } + /** Takes text containing mentions and hashtags and makes them the given colour. */ public static void highlightSpans(Spannable text, int colour) { // Strip all existing colour spans. int n = text.length(); diff --git a/app/src/main/java/com/keylesspalace/tusky/util/ThemeUtils.java b/app/src/main/java/com/keylesspalace/tusky/util/ThemeUtils.java index 310341fa..6666c8fa 100644 --- a/app/src/main/java/com/keylesspalace/tusky/util/ThemeUtils.java +++ b/app/src/main/java/com/keylesspalace/tusky/util/ThemeUtils.java @@ -26,6 +26,10 @@ import android.support.v4.content.ContextCompat; import android.util.TypedValue; import android.widget.ImageView; +/** + * Provides runtime compatibility to obtain theme information and re-theme views, especially where + * the ability to do so is not supported in resource files. + */ public class ThemeUtils { public static Drawable getDrawable(Context context, @AttrRes int attribute, @DrawableRes int fallbackDrawable) {