From eeea0774b617162bafe08b28d530d861bfa9f656 Mon Sep 17 00:00:00 2001 From: Clay Tsay <9517278+claytsay@users.noreply.github.com> Date: Sun, 10 Dec 2017 00:28:51 -0800 Subject: [PATCH] Added JavaDocs Added JavaDocs to various files, namely License, Media, PageTitle, and Utils. --- .../java/fr/free/nrw/commons/License.java | 18 ++++ .../main/java/fr/free/nrw/commons/Media.java | 90 +++++++++++++++++++ .../java/fr/free/nrw/commons/PageTitle.java | 6 ++ .../main/java/fr/free/nrw/commons/Utils.java | 6 ++ 4 files changed, 120 insertions(+) diff --git a/app/src/main/java/fr/free/nrw/commons/License.java b/app/src/main/java/fr/free/nrw/commons/License.java index 797e0f50c..7b75cfda8 100644 --- a/app/src/main/java/fr/free/nrw/commons/License.java +++ b/app/src/main/java/fr/free/nrw/commons/License.java @@ -8,6 +8,16 @@ public class License { private String url; private String name; + /** + * Constructs a new instance of License. + * + * @param key license key + * @param template license template + * @param url license URL + * @param name licence name + * + * @throws RuntimeException if License.key or Licence.template is null + */ public License(String key, String template, String url, String name) { if (key == null) { throw new RuntimeException("License.key must not be null"); @@ -21,10 +31,18 @@ public class License { this.name = name; } + /** + * Gets the license key. + * @return license key as a String. + */ public String getKey() { return key; } + /** + * Gets the license template. + * @return license template as a String. + */ public String getTemplate() { return template; } diff --git a/app/src/main/java/fr/free/nrw/commons/Media.java b/app/src/main/java/fr/free/nrw/commons/Media.java index 21e6cfe9e..c7eaf63d5 100644 --- a/app/src/main/java/fr/free/nrw/commons/Media.java +++ b/app/src/main/java/fr/free/nrw/commons/Media.java @@ -128,89 +128,179 @@ public class Media implements Parcelable { return imageUrl; } + /** + * Gets the name of the file. + * @return file name as a string + */ public String getFilename() { return filename; } + /** + * Sets the name of the file. + * @param filename the new name of the file + */ public void setFilename(String filename) { this.filename = filename; } + /** + * Gets the file description. + * @return file description as a string + */ public String getDescription() { return description; } + /** + * Sets the file description. + * @param description the new description of the file + */ public void setDescription(String description) { this.description = description; } + /** + * Gets the datalength of the file. + * @return file datalength as a long + */ public long getDataLength() { return dataLength; } + /** + * Sets the datalength of the file. + * @param dataLength as a long + */ public void setDataLength(long dataLength) { this.dataLength = dataLength; } + /** + * Gets the creation date of the file. + * @return creation date as a Date + */ public Date getDateCreated() { return dateCreated; } + /** + * Sets the creation date of the file. + * @param date creation date as a Date + */ public void setDateCreated(Date date) { this.dateCreated = date; } + /** + * Gets the upload date of the file. + * Can be null. + * @return upload date as a Date + */ public @Nullable Date getDateUploaded() { return dateUploaded; } + /** + * Gets the name of the creator of the file. + * @return creator name as a String + */ public String getCreator() { return creator; } + /** + * Sets the creator name of the file. + * @param creator creator name as a string + */ public void setCreator(String creator) { this.creator = creator; } + /** + * Gets the width of the media. + * @return file width as an int + */ public int getWidth() { return width; } + /** + * Sets the width of the media. + * @param width file width as an int + */ public void setWidth(int width) { this.width = width; } + /** + * Gets the height of the media. + * @return file height as an int + */ public int getHeight() { return height; } + /** + * Sets the height of the media. + * @param height file height as an int + */ public void setHeight(int height) { this.height = height; } + /** + * Gets the license name of the file. + * @return license as a String + */ public String getLicense() { return license; } + /** + * Sets the license name of the file. + * @param license license name as a String + */ public void setLicense(String license) { this.license = license; } + /** + * Gets the coordinates of the file. + *

+ * Presumably indicates upload location. + * @return file coordinates as a LatLng + */ public @Nullable LatLng getCoordinates() { return coordinates; } + /** + * Sets the coordinates of the file. + * @param coordinates file coordinates as a LatLng + */ public void setCoordinates(@Nullable LatLng coordinates) { this.coordinates = coordinates; } + /** + * Gets the categories the file falls under. + * @return file categories as an ArrayList of Strings + */ @SuppressWarnings("unchecked") public ArrayList getCategories() { return (ArrayList) categories.clone(); // feels dirty } + /** + * Sets the categories the file falls under. + *

+ * Does not append: i.e. will clear the current categories + * and then add the specified ones. + * @param categories file categories as a list of Strings + */ public void setCategories(List categories) { this.categories.clear(); this.categories.addAll(categories); diff --git a/app/src/main/java/fr/free/nrw/commons/PageTitle.java b/app/src/main/java/fr/free/nrw/commons/PageTitle.java index 6229e7ef9..c4c52b1fc 100644 --- a/app/src/main/java/fr/free/nrw/commons/PageTitle.java +++ b/app/src/main/java/fr/free/nrw/commons/PageTitle.java @@ -84,6 +84,12 @@ public class PageTitle { return titleKey; } + /** + * Gets the canonicalized title for displaying (such as "File:My example.jpg"). + *

+ * Essentially equivalent to getPrefixedText + * @return canonical title as a String + */ @Override public String toString() { return getPrefixedText(); diff --git a/app/src/main/java/fr/free/nrw/commons/Utils.java b/app/src/main/java/fr/free/nrw/commons/Utils.java index 3f5eb2105..87dab7f68 100644 --- a/app/src/main/java/fr/free/nrw/commons/Utils.java +++ b/app/src/main/java/fr/free/nrw/commons/Utils.java @@ -51,6 +51,12 @@ public class Utils { } } + /** + * Capitalizes the first character of a string. + * + * @param string + * @return string with capitalized first character + */ public static String capitalize(String string) { return string.substring(0, 1).toUpperCase(Locale.getDefault()) + string.substring(1); }