Add docs

Author: wipfli

tiles/src/main/java/com/protomaps/basemap/feature/Matcher.java

@@ -8,9 +8,52 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * A utility class for matching source feature properties to values.
+ * 
+ * <p>
+ * Use the {@link #rule} function to create entries for a Planetiler {@link MultiExpression}. A rule consists of
+ * multiple contitions that get joined by a logical AND, and key-value pairs that should be used if all conditions of
+ * the rule are true. The key-value pairs of rules that get added later override the key-value pairs of rules that were
+ * added earlier.
+ * </p>
+ * 
+ * <p>
+ * The MultiExpression can be used on a source feature and the resulting list of matches can be used in
+ * {@link #getString} and similar functions to retrieve a value.
+ * </p>
+ * 
+ * <p>
+ * Example usage:
+ * </p>
+ * 
+ * <pre>
+ * <code>
+ *var index = MultiExpression.of(List.of(rule(with("highway", "primary"), use("kind", "major_road")))).index();
+ *var matches = index.getMatches(sourceFeature);
+ *String kind = getString(sourceFeature, matches, "kind", "other");
+ * </code>
+ * </pre>
+ */
 public class Matcher {
   public record Use(String key, Object value) {}
 
+  /**
+   * Creates a matching rule with conditions and values.
+   * 
+   * <p>
+   * Create conditions by calling the {@link #with} or {@link #without} functions. All conditions are joined by a
+   * logical AND.
+   * </p>
+   * 
+   * <p>
+   * Create key-value pairs with the {@link #use} function.
+   * </p>
+   * 
+   * @param arguments A mix of {@link Use} instances for key-value pairs and {@link Expression} instances for
+   *                  conditions.
+   * @return A {@link MultiExpression.Entry} containing the rule definition.
+   */
   public static MultiExpression.Entry<Map<String, Object>> rule(Object... arguments) {
     Map<String, Object> result = new HashMap<>();
     List<Expression> conditions = new ArrayList<>();
@@ -24,10 +67,50 @@ public static MultiExpression.Entry<Map<String, Object>> rule(Object... argument
     return MultiExpression.entry(result, Expression.and(conditions));
   }
 
+  /**
+   * Creates a {@link Use} instance representing a key-value pair to be supplied to the {@link #rule} function.
+   * 
+   * <p>
+   * While in principle any Object can be supplied as value, retrievalbe later on are only Strings with
+   * {@link #getString}, Integers with {@link #getInteger}, Doubles with {@link #getDouble}, Booleans with
+   * {@link #getBoolean}.
+   * </p>
+   * 
+   * @param key   The key.
+   * @param value The value associated with the key.
+   * @return A new {@link Use} instance.
+   */
   public static Use use(String key, Object value) {
     return new Use(key, value);
   }
 
+  /**
+   * Creates an {@link Expression} that matches any of the specified arguments.
+   * 
+   * <p>
+   * If no argument is supplied, matches everything.
+   * </p>
+   * 
+   * <p>
+   * If one argument is supplied, matches all source features that have this tag, e.g., {@code with("highway")} matches
+   * to all source features with a highway tag.
+   * </p>
+   * 
+   * <p>
+   * If two arguments are supplied, matches to all source features that have this tag-value pair, e.g.,
+   * {@code with("highway", "primary")} matches to all source features with highway=primary.
+   * </p>
+   * 
+   * <p>
+   * If more than two arguments are supplied, matches to all source features that have the first argument as tag and the
+   * later arguments as possible values, e.g., {@code with("highway", "primary", "secondary")} matches to all source
+   * features that have highway=primary or highway=secondary.
+   * </p>
+   * .
+   * 
+   * @param arguments Field names to match.
+   * @return An {@link Expression} for the given field names.
+   */
   public static Expression with(String... arguments) {
     List<String> argumentList = List.of(arguments);
     if (argumentList.isEmpty()) {
@@ -38,12 +121,39 @@ public static Expression with(String... arguments) {
     return Expression.matchAny(argumentList.getFirst(), argumentList.subList(1, argumentList.size()));
   }
 
+  /**
+   * Same as {@link #with}, but negated.
+   */
   public static Expression without(String... arguments) {
     return Expression.not(with(arguments));
   }
 
   public record FromTag(String key) {}
 
+  /**
+   * Creates a {@link FromTag} instance representing a tag reference.
+   * 
+   * <p>
+   * Use this function if to retrieve a value from a source feature when calling {@link #getString} and similar.
+   * </p>
+   * 
+   * <p>
+   * Example usage:
+   * </p>
+   * 
+   * <pre>
+   * <code>
+   *var index = MultiExpression.of(List.of(rule(with("highway", "primary", "secondary"), use("kind", fromTag("highway"))))).index();
+   *var matches = index.getMatches(sourceFeature);
+   *String kind = getString(sourceFeature, matches, "kind", "other");
+   * </code>
+   * </pre>
+   * <p>
+   * On a source feature with highway=primary the above will result in kind=primary.
+   * 
+   * @param key The key of the tag.
+   * @return A new {@link FromTag} instance.
+   */
   public static FromTag fromTag(String key) {
     return new FromTag(key);
   }