Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 95d5ab30 authored by Elliott Hughes's avatar Elliott Hughes
Browse files

Improve the Resource.getQuantityString/getQuantityText documentation. 

Natural languages differ so much and in such odd ways that you can't
use getQuantityString as an "if" statement. It's really just for grammaticality.
This is explained well in
http://developer.android.com/guide/topics/resources/string-resource.html#Plurals
but we need to make more of an effort to motivate people to read that, and to
at least get the most important point across if they don't read it.

Change-Id: I549b9f3563462c45f2dea34c558185e0714127cd
parent 0c25ecfd

core/java/android/content/res/Resources.java

+25 −18
Original line number Diff line number Diff line
@@ -232,11 +232,13 @@ public class Resources { 
    }



    /**

     * Return the character sequence associated with a particular resource ID for a particular

     * numerical quantity.

     *

     * <p>See <a href="{@docRoot}guide/topics/resources/string-resource.html#Plurals">String

     * Resources</a> for more on quantity strings.

     * Returns the character sequence necessary for grammatically correct pluralization

     * of the given resource ID for the given quantity.

     * Note that the character sequence is selected based solely on grammatical necessity,

     * and that such rules differ between languages. Do not assume you know which string

     * will be returned for a given quantity. See

     * <a href="{@docRoot}guide/topics/resources/string-resource.html#Plurals">String Resources</a>

     * for more detail.

     *

     * @param id The desired resource identifier, as generated by the aapt

     *           tool. This integer encodes the package, type, and resource
@@ -344,14 +346,17 @@ public class Resources { 
    }



    /**

     * Return the string value associated with a particular resource ID for a particular

     * numerical quantity, substituting the format arguments as defined in

     * {@link java.util.Formatter} and {@link java.lang.String#format}. It will be

     * stripped of any styled text information.

     * {@more}

     * Formats the string necessary for grammatically correct pluralization

     * of the given resource ID for the given quantity, using the given arguments.

     * Note that the string is selected based solely on grammatical necessity,

     * and that such rules differ between languages. Do not assume you know which string

     * will be returned for a given quantity. See

     * <a href="{@docRoot}guide/topics/resources/string-resource.html#Plurals">String Resources</a>

     * for more detail.

     *

     * <p>See <a href="{@docRoot}guide/topics/resources/string-resource.html#Plurals">String

     * Resources</a> for more on quantity strings.

     * <p>Substitution of format arguments works as if using

     * {@link java.util.Formatter} and {@link java.lang.String#format}.

     * The resulting string will be stripped of any styled text information.

     *

     * @param id The desired resource identifier, as generated by the aapt

     *           tool. This integer encodes the package, type, and resource
@@ -372,11 +377,13 @@ public class Resources { 
    }



    /**

     * Return the string value associated with a particular resource ID for a particular

     * numerical quantity.

     *

     * <p>See <a href="{@docRoot}guide/topics/resources/string-resource.html#Plurals">String

     * Resources</a> for more on quantity strings.

     * Returns the string necessary for grammatically correct pluralization

     * of the given resource ID for the given quantity.

     * Note that the string is selected based solely on grammatical necessity,

     * and that such rules differ between languages. Do not assume you know which string

     * will be returned for a given quantity. See

     * <a href="{@docRoot}guide/topics/resources/string-resource.html#Plurals">String Resources</a>

     * for more detail.

     *

     * @param id The desired resource identifier, as generated by the aapt

     *           tool. This integer encodes the package, type, and resource