Changeset 7530 in josm for trunk/src


Ignore:
Timestamp:
2014-09-12T16:11:41+02:00 (10 years ago)
Author:
Don-vip
Message:

improve mapcss javadoc

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/org/openstreetmap/josm/gui/mappaint/mapcss/ExpressionFactory.java

    r7509 r7530  
    2828import org.openstreetmap.josm.data.osm.Node;
    2929import org.openstreetmap.josm.data.osm.OsmPrimitive;
     30import org.openstreetmap.josm.data.osm.Way;
    3031import org.openstreetmap.josm.gui.mappaint.Cascade;
    3132import org.openstreetmap.josm.gui.mappaint.Environment;
    … …  
    120121        }
    121122
     123        /**
     124         * Function associated to the numeric "+" operator.
     125         * @param args arguments
     126         * @return Sum of arguments
     127         */
    122128        public static float plus(float... args) {
    123129            float res = 0;
    … …  
    128134        }
    129135
     136        /**
     137         * Function associated to the numeric "-" operator.
     138         * @param args arguments
     139         * @return Substraction of arguments
     140         */
    130141        public static Float minus(float... args) {
    131142            if (args.length == 0) {
    … …  
    142153        }
    143154
     155        /**
     156         * Function associated to the numeric "*" operator.
     157         * @param args arguments
     158         * @return Multiplication of arguments
     159         */
    144160        public static float times(float... args) {
    145161            float res = 1;
    … …  
    150166        }
    151167
     168        /**
     169         * Function associated to the numeric "/" operator.
     170         * @param args arguments
     171         * @return Division of arguments
     172         */
    152173        public static Float divided_by(float... args) {
    153174            if (args.length == 0) {
    … …  
    166187        /**
    167188         * Creates a list of values, e.g., for the {@code dashes} property.
     189         * @param args The values to put in a list
     190         * @return list of values
    168191         * @see Arrays#asList(Object[])
    169192         */
    … …  
    183206        /**
    184207         * Returns the first non-null object. The name originates from the {@code COALESCE} SQL function.
     208         * @param args arguments
     209         * @return the first non-null object
    185210         * @deprecated Deprecated in favour of {@link #any(Object...)} from the MapCSS standard.
    186211         */
    … …  
    194219         * Returns the first non-null object.
    195220         * The name originates from <a href="http://wiki.openstreetmap.org/wiki/MapCSS/0.2/eval">MapCSS standard</a>.
     221         * @param args arguments
     222         * @return the first non-null object
    196223         * @see #coalesce(Object...)
    197224         * @see Utils#firstNonNull(Object[])
    … …  
    204231        /**
    205232         * Get the {@code n}th element of the list {@code lst} (counting starts at 0).
     233         * @param lst list
     234         * @param n index
     235         * @return {@code n}th element of the list, or {@code null} if index out of range
    206236         * @since 5699
    207237         */
    … …  
    216246        /**
    217247         * Splits string {@code toSplit} at occurrences of the separator string {@code sep} and returns a list of matches.
     248         * @param sep separator string
     249         * @param toSplit string to split
     250         * @return list of matches
    218251         * @see String#split(String)
    219252         * @since 5699
    … …  
    225258        /**
    226259         * Creates a color value with the specified amounts of {@code r}ed, {@code g}reen, {@code b}lue (arguments from 0.0 to 1.0)
     260         * @param r the red component
     261         * @param g the green component
     262         * @param b the blue component
     263         * @return color matching the given components
    227264         * @see Color#Color(float, float, float)
    228265         */
    … …  
    235272        }
    236273
     274        /**
     275         * Creates a color value with the specified amounts of {@code r}ed, {@code g}reen, {@code b}lue, {@code alpha} (arguments from 0.0 to 1.0)
     276         * @param r the red component
     277         * @param g the green component
     278         * @param b the blue component
     279         * @param alpha the alpha component
     280         * @return color matching the given components
     281         * @see Color#Color(float, float, float, float)
     282         */
    237283        public static Color rgba(float r, float g, float b, float alpha) {
    238284            try {
    … …  
    260306        /**
    261307         * Creates a color value from an HTML notation, i.e., {@code #rrggbb}.
     308         * @param html HTML notation
     309         * @return color matching the given notation
    262310         */
    263311        public static Color html2color(String html) {
    … …  
    267315        /**
    268316         * Computes the HTML notation ({@code #rrggbb}) for a color value).
     317         * @param c color
     318         * @return HTML notation matching the given color
    269319         */
    270320        public static String color2html(Color c) {
    … …  
    274324        /**
    275325         * Get the value of the red color channel in the rgb color model
     326         * @param c color
    276327         * @return the red color channel in the range [0;1]
    277328         * @see java.awt.Color#getRed()
    … …  
    283334        /**
    284335         * Get the value of the green color channel in the rgb color model
     336         * @param c color
    285337         * @return the green color channel in the range [0;1]
    286338         * @see java.awt.Color#getGreen()
    … …  
    292344        /**
    293345         * Get the value of the blue color channel in the rgb color model
     346         * @param c color
    294347         * @return the blue color channel in the range [0;1]
    295348         * @see java.awt.Color#getBlue()
    … …  
    301354        /**
    302355         * Get the value of the alpha channel in the rgba color model
     356         * @param c color
    303357         * @return the alpha channel in the range [0;1]
    304358         * @see java.awt.Color#getAlpha()
    … …  
    310364        /**
    311365         * Assembles the strings to one.
     366         * @param args arguments
     367         * @return assembled string
    312368         * @see Utils#join
    313369         */
    … …  
    319375        /**
    320376         * Assembles the strings to one, where the first entry is used as separator.
     377         * @param args arguments. First one is used as separator
     378         * @return assembled string
    321379         * @see Utils#join
    322380         */
    … …  
    328386        /**
    329387         * Returns the value of the property {@code key}, e.g., {@code prop("width")}.
     388         * @param env the environment
     389         * @param key the property key
     390         * @return the property value
    330391         */
    331392        public static Object prop(final Environment env, String key) {
    … …  
    335396        /**
    336397         * Returns the value of the property {@code key} from layer {@code layer}.
     398         * @param env the environment
     399         * @param key the property key
     400         * @return the property value
    337401         */
    338402        public static Object prop(final Environment env, String key, String layer) {
    … …  
    342406        /**
    343407         * Determines whether property {@code key} is set.
     408         * @param env the environment
     409         * @param key the property key
     410         * @return {@code true} if the property is set, {@code false} otherwise
    344411         */
    345412        public static Boolean is_prop_set(final Environment env, String key) {
    … …  
    349416        /**
    350417         * Determines whether property {@code key} is set on layer {@code layer}.
     418         * @param env the environment
     419         * @param key the property key
     420         * @return {@code true} if the property is set, {@code false} otherwise
    351421         */
    352422        public static Boolean is_prop_set(final Environment env, String key, String layer) {
    … …  
    356426        /**
    357427         * Gets the value of the key {@code key} from the object in question.
     428         * @param env the environment
     429         * @param key the OSM key
     430         * @return the value for given key
    358431         */
    359432        public static String tag(final Environment env, String key) {
    … …  
    363436        /**
    364437         * Gets the first non-null value of the key {@code key} from the object's parent(s).
     438         * @param env the environment
     439         * @param key the OSM key
     440         * @return first non-null value of the key {@code key} from the object's parent(s)
    365441         */
    366442        public static String parent_tag(final Environment env, String key) {
    … …  
    380456        }
    381457
     458        /**
     459         * Gets the value of the key {@code key} from the object's child.
     460         * @param env the environment
     461         * @param key the OSM key
     462         * @return the value of the key {@code key} from the object's child, or {@code null} if there is no child
     463         */
    382464        public static String child_tag(final Environment env, String key) {
    383465            return env.child == null ? null : env.child.get(key);
    … …  
    386468        /**
    387469         * Determines whether the object has a tag with the given key.
     470         * @param env the environment
     471         * @param key the OSM key
     472         * @return {@code true} if the object has a tag with the given key, {@code false} otherwise
    388473         */
    389474        public static boolean has_tag_key(final Environment env, String key) {
    … …  
    393478        /**
    394479         * Returns the index of node in parent way or member in parent relation.
     480         * @param env the environment
     481         * @return the index as float. Starts at 1
    395482         */
    396483        public static Float index(final Environment env) {
    … …  
    401488        }
    402489
     490        /**
     491         * Returns the role of current object in parent relation, or role of child if current object is a relation.
     492         * @param env the environment
     493         * @return role of current object in parent relation, or role of child if current object is a relation
     494         * @see Environment#getRole()
     495         */
    403496        public static String role(final Environment env) {
    404497            return env.getRole();
    405498        }
    406499
     500        /**
     501         * Function associated to the logical "!" operator.
     502         * @param b boolean value
     503         * @return {@code true} if {@code !b}
     504         */
    407505        public static boolean not(boolean b) {
    408506            return !b;
    409507        }
    410508
     509        /**
     510         * Function associated to the logical ">=" operator.
     511         * @param a first value
     512         * @param b second value
     513         * @return {@code true} if {@code a >= b}
     514         */
    411515        public static boolean greater_equal(float a, float b) {
    412516            return a >= b;
    413517        }
    414518
     519        /**
     520         * Function associated to the logical "<=" operator.
     521         * @param a first value
     522         * @param b second value
     523         * @return {@code true} if {@code a <= b}
     524         */
    415525        public static boolean less_equal(float a, float b) {
    416526            return a <= b;
    417527        }
    418528
     529        /**
     530         * Function associated to the logical ">" operator.
     531         * @param a first value
     532         * @param b second value
     533         * @return {@code true} if {@code a > b}
     534         */
    419535        public static boolean greater(float a, float b) {
    420536            return a > b;
    421537        }
    422538
     539        /**
     540         * Function associated to the logical "<" operator.
     541         * @param a first value
     542         * @param b second value
     543         * @return {@code true} if {@code a < b}
     544         */
    423545        public static boolean less(float a, float b) {
    424546            return a < b;
    … …  
    427549        /**
    428550         * Determines if the objects {@code a} and {@code b} are equal.
     551         * @param a First object
     552         * @param b Second object
     553         * @return {@code true} if objects are equal, {@code false} otherwise
    429554         * @see Object#equals(Object)
    430555         */
    … …  
    437562        /**
    438563         * Determines whether the JOSM search with {@code searchStr} applies to the object.
     564         * @param env the environment
     565         * @param searchStr the search string
     566         * @return {@code true} if the JOSM search with {@code searchStr} applies to the object
     567         * @see SearchCompiler
    439568         */
    440569        public static Boolean JOSM_search(final Environment env, String searchStr) {
    … …  
    451580         * Obtains the JOSM'key {@link org.openstreetmap.josm.data.Preferences} string for key {@code key},
    452581         * and defaults to {@code def} if that is null.
     582         * @param key Key in JOSM preference
     583         * @param def Default value
     584         * @return value for key, or default value if not found
    453585         * @see org.openstreetmap.josm.data.Preferences#get(String, String)
    454586         */
    … …  
    460592        /**
    461593         * Tests if string {@code target} matches pattern {@code pattern}
     594         * @param pattern The regex expression
     595         * @param target The character sequence to be matched
     596         * @return {@code true} if, and only if, the entire region sequence matches the pattern
    462597         * @see Pattern#matches(String, CharSequence)
    463598         * @since 5699
    … …  
    469604        /**
    470605         * Tests if string {@code target} matches pattern {@code pattern}
     606         * @param pattern The regex expression
     607         * @param target The character sequence to be matched
    471608         * @param flags a string that may contain "i" (case insensitive), "m" (multiline) and "s" ("dot all")
     609         * @return {@code true} if, and only if, the entire region sequence matches the pattern
     610         * @see Pattern#CASE_INSENSITIVE
     611         * @see Pattern#DOTALL
     612         * @see Pattern#MULTILINE
    472613         * @since 5699
    473614         */
    … …  
    490631         * The first element (index 0) is the complete match (i.e. string).
    491632         * Further elements correspond to the bracketed parts of the regular expression.
     633         * @param pattern The regex expression
     634         * @param target The character sequence to be matched
    492635         * @param flags a string that may contain "i" (case insensitive), "m" (multiline) and "s" ("dot all")
     636         * @return a list of capture groups if {@link Matcher#matches()}, or {@code null}.
     637         * @see Pattern#CASE_INSENSITIVE
     638         * @see Pattern#DOTALL
     639         * @see Pattern#MULTILINE
    493640         * @since 5701
    494641         */
    … …  
    504651                f |= Pattern.MULTILINE;
    505652            }
    506             Matcher m = Pattern.compile(pattern, f).matcher(target);
    507             return Utils.getMatches(m);
     653            return Utils.getMatches(Pattern.compile(pattern, f).matcher(target));
    508654        }
    509655
    … …  
    512658         * The first element (index 0) is the complete match (i.e. string).
    513659         * Further elements correspond to the bracketed parts of the regular expression.
     660         * @param pattern The regex expression
     661         * @param target The character sequence to be matched
     662         * @return a list of capture groups if {@link Matcher#matches()}, or {@code null}.
    514663         * @since 5701
    515664         */
    516665        public static List<String> regexp_match(String pattern, String target) {
    517             Matcher m = Pattern.compile(pattern).matcher(target);
    518             return Utils.getMatches(m);
     666            return Utils.getMatches(Pattern.compile(pattern).matcher(target));
    519667        }
    520668
    521669        /**
    522670         * Returns the OSM id of the current object.
     671         * @param env the environment
     672         * @return the OSM id of the current object
    523673         * @see OsmPrimitive#getUniqueId()
    524674         */
    … …  
    529679        /**
    530680         * Translates some text for the current locale. The first argument is the text to translate,
    531          * and the subsequent arguments are parameters for the string indicated by {@code {0}}, {@code {1}}, …
     681         * and the subsequent arguments are parameters for the string indicated by <code>{0}</code>, <code>{1}</code>, …
     682         * @param args arguments
     683         * @return the translated string
    532684         */
    533685        @NullableArguments
    … …  
    564716        /**
    565717         * Replaces in {@code s} every {@code} target} substring by {@code replacement}.
    566          * * @see String#replace(CharSequence, CharSequence)
     718         * @param s The source string
     719         * @param target The sequence of char values to be replaced
     720         * @param replacement The replacement sequence of char values
     721         * @return The resulting string
     722         * @see String#replace(CharSequence, CharSequence)
    567723         */
    568724        public static String replace(String s, String target, String replacement) {
    … …  
    722878        private Expression condition, firstOption, secondOption;
    723879
     880        /**
     881         * Constructs a new {@code CondOperator}.
     882         * @param condition condition
     883         * @param firstOption first option
     884         * @param secondOption second option
     885         */
    724886        public CondOperator(Expression condition, Expression firstOption, Expression secondOption) {
    725887            this.condition = condition;
    … …  
    738900    }
    739901
     902    /**
     903     * "And" logical operator.
     904     */
    740905    public static class AndOperator implements Expression {
    741906
    742907        private List<Expression> args;
    743908
     909        /**
     910         * Constructs a new {@code AndOperator}.
     911         * @param args arguments
     912         */
    744913        public AndOperator(List<Expression> args) {
    745914            this.args = args;
    … …  
    758927    }
    759928
     929    /**
     930     * "Or" logical operator.
     931     */
    760932    public static class OrOperator implements Expression {
    761933
    762934        private List<Expression> args;
    763935
     936        /**
     937         * Constructs a new {@code OrOperator}.
     938         * @param args arguments
     939         */
    764940        public OrOperator(List<Expression> args) {
    765941            this.args = args;
    … …  
    779955
    780956    /**
    781      * Function to calculate the length of a string or list in a MapCSS eval
    782      * expression.
     957     * Function to calculate the length of a string or list in a MapCSS eval expression.
    783958     *
    784      * Separate implementation to support overloading for different
    785      * argument types.
     959     * Separate implementation to support overloading for different argument types.
    786960     *
    787961     * The use for calculating the length of a list is deprecated, use
    … …  
    792966        private Expression arg;
    793967
     968        /**
     969         * Constructs a new {@code LengthFunction}.
     970         * @param args arguments
     971         */
    794972        public LengthFunction(Expression args) {
    795973            this.arg = args;
    … …  
    816994        private final boolean computeMax;
    817995
     996        /**
     997         * Constructs a new {@code MinMaxFunction}.
     998         * @param args arguments
     999         * @param computeMax if {@code true}, compute max. If {@code false}, compute min
     1000         */
    8181001        public MinMaxFunction(final List<Expression> args, final boolean computeMax) {
    8191002            this.args = args;
    … …  
    8601043        private final boolean needsEnvironment;
    8611044
     1045        /**
     1046         * Constructs a new {@code ParameterFunction}.
     1047         */
    8621048        public ParameterFunction(Method m, List<Expression> args, boolean needsEnvironment) {
    8631049            this.m = m;
    … …  
    9141100            return b.toString();
    9151101        }
    916 
    9171102    }
    9181103
    … …  
    9321117        private final Class<?> arrayComponentType;
    9331118
     1119        /**
     1120         * Constructs a new {@code ArrayFunction}.
     1121         */
    9341122        public ArrayFunction(Method m, List<Expression> args) {
    9351123            this.m = m;
    … …  
    9641152            return result;
    9651153        }
     1154
    9661155        @Override
    9671156        public String toString() {
    … …  
    9761165            return b.toString();
    9771166        }
    978 
    9791167    }
    980 
    9811168}
Note: See TracChangeset for help on using the changeset viewer.