fix typos and normalize class documentation

src/main/java/de/komoot/photon/App.java

@@ -17,7 +17,9 @@
 
 import static spark.Spark.*;
 
-
+/**
+ * Main Photon application.
+ */
 public class App {
     private static final Logger LOGGER = org.slf4j.LoggerFactory.getLogger(App.class);
 
@@ -59,7 +61,7 @@ public static void main(String[] rawArgs) throws Exception {
                 return;
             }
 
-            // no special action specified -> normal mode: start search API
+            // No special action specified -> normal mode: start search API
             startApi(args, esServer);
         } finally {
             if (shutdownES) esServer.shutdown();
@@ -94,9 +96,7 @@ private static CommandLineArgs parseCommandLine(String[] rawArgs) {
 
 
     /**
-     * take nominatim data and dump it to json
-     *
-     * @param args
+     * Take nominatim data and dump it to a Json file.
      */
     private static void startJsonDump(CommandLineArgs args) {
         try {
@@ -137,9 +137,9 @@ private static void startNominatimUpdateInit(CommandLineArgs args) {
     }
 
 
-        /**
-         * Prepare Nominatim updater.
-         */
+    /**
+     * Prepare Nominatim updater.
+     */
     private static NominatimUpdater setupNominatimUpdater(CommandLineArgs args, Server server) {
         // Get database properties and ensure that the version is compatible.
         DatabaseProperties dbProperties = new DatabaseProperties();
@@ -168,7 +168,7 @@ private static void startApi(CommandLineArgs args, Server server) {
         if (allowedOrigin != null) {
             CorsFilter.enableCORS(allowedOrigin, "get", "*");
         } else {
-            // Set Json content type. In the other case set by enableCors.
+            // Set Json content type. In the other case already set by enableCors.
             before((request, response) -> response.type("application/json; charset=UTF-8"));
         }
 

src/main/java/de/komoot/photon/CommandLineArgs.java

@@ -1,87 +1,85 @@
 package de.komoot.photon;
 
-/**
- * Command Line Arguments parsed by {@link com.beust.jcommander.JCommander} and used to start photon.
- */
-
 import com.beust.jcommander.Parameter;
 import de.komoot.photon.utils.StringArrayConverter;
 
 import java.io.File;
 
-
+/**
+ * Command Line Arguments parsed by {@link com.beust.jcommander.JCommander} and used to start photon.
+ */
 public class CommandLineArgs {
 
-    @Parameter(names = "-cluster", description = "name of elasticsearch cluster to put the server into (default is 'photon')")
+    @Parameter(names = "-cluster", description = "Name of ElasticSearch cluster to put the server into")
     private String cluster = "photon";
 
-    @Parameter(names = "-transport-addresses", description = "the comma separated addresses of external elasticsearch nodes where the client can connect to (default is an empty string which forces an internal node to start)", converter = StringArrayConverter.class)
+    @Parameter(names = "-transport-addresses", description = "Comma-separated list of addresses of external ElasticSearch nodes the client can connect to (default is an empty string which forces an internal node to start)", converter = StringArrayConverter.class)
     private String[] transportAddresses = new String[]{};
 
-    @Parameter(names = "-nominatim-import", description = "import nominatim database into photon (this will delete previous index)")
+    @Parameter(names = "-nominatim-import", description = "Import nominatim database into photon (this will delete previous index)")
     private boolean nominatimImport = false;
 
-    @Parameter(names = "-nominatim-update-init-for", description = "set up tracking of updates in the Nominatim database for the given user and exit")
+    @Parameter(names = "-nominatim-update-init-for", description = "Set up tracking of updates in the Nominatim database for the given user and exit")
     private String nominatimUpdateInit = null;
 
-    @Parameter(names = "-nominatim-update", description = "fetch updates from nominatim database into photon and exit (this updates the index only without offering an API)")
+    @Parameter(names = "-nominatim-update", description = "Fetch updates from nominatim database into photon and exit (updates the index only without offering an API)")
     private boolean nominatimUpdate = false;
 
-    @Parameter(names = "-languages", description = "languages nominatim importer should import and use at run-time, comma separated (default is 'en,fr,de,it')", converter = StringArrayConverter.class)
+    @Parameter(names = "-languages", description = "[import-only] Comma-separated list of languages for which names should be imported (default is 'en,fr,de,it')", converter = StringArrayConverter.class)
     private String[] languages = new String[]{};
 
-    @Parameter(names = "-default-language", description = "language to return results in when no explicit language is choosen by the user")
+    @Parameter(names = "-default-language", description = "Language to return results in when no explicit language is chosen by the user")
     private String defaultLanguage = "default";
 
-    @Parameter(names = "-country-codes", description = "country codes filter that nominatim importer should import, comma separated. If empty full planet is done", converter = StringArrayConverter.class)
+    @Parameter(names = "-country-codes", description = "[import-only] Comma-separated list of country codes for countries the importer should import, comma separated (default is empty which imports the full database)", converter = StringArrayConverter.class)
     private String[] countryCodes = new String[]{};
 
-    @Parameter(names = "-extra-tags", description = "comma-separated list of additional tags to save for each place", converter = StringArrayConverter.class)
+    @Parameter(names = "-extra-tags", description = "Comma-separated list of additional tags to save for each place (default: None)", converter = StringArrayConverter.class)
     private String[] extraTags = new String[]{};
 
-    @Parameter(names = "-synonym-file", description = "file with synonym and classification terms")
+    @Parameter(names = "-synonym-file", description = "File with synonym and classification terms")
     private String synonymFile = null;
 
     @Parameter(names = "-query-timeout", description = "Time after which to cancel queries to the ES database (in seconds).")
     private int queryTimeout = 7;
 
-    @Parameter(names = "-json", description = "import nominatim database and dump it to a json like files in (useful for developing)")
+    @Parameter(names = "-json", description = "Read from nominatim database and dump it to the given file in a json-like format (useful for developing)")
     private String jsonDump = null;
 
-    @Parameter(names = "-host", description = "postgres host (default 127.0.0.1)")
+    @Parameter(names = "-host", description = "Hostname of the PostgreSQL database")
     private String host = "127.0.0.1";
 
-    @Parameter(names = "-port", description = "postgres port (default 5432)")
+    @Parameter(names = "-port", description = "Port of the PostgreSQL database")
     private Integer port = 5432;
 
-    @Parameter(names = "-database", description = "postgres host (default nominatim)")
+    @Parameter(names = "-database", description = "Database name of the Nominatim database")
     private String database = "nominatim";
 
-    @Parameter(names = "-user", description = "postgres user (default nominatim)")
+    @Parameter(names = "-user", description = "Username in the PostgreSQL database")
     private String user = "nominatim";
 
-    @Parameter(names = "-password", description = "postgres password (default '')")
+    @Parameter(names = "-password", description = "Password for the PostgreSQL database")
     private String password = null;
 
-    @Parameter(names = "-data-dir", description = "data directory (default '.')")
+    @Parameter(names = "-data-dir", description = "Photon data directory")
     private String dataDirectory = new File(".").getAbsolutePath();
 
-    @Parameter(names = "-listen-port", description = "listen to port (default 2322)")
+    @Parameter(names = "-listen-port", description = "Port for the Photon server to listen to")
     private int listenPort = 2322;
 
-    @Parameter(names = "-listen-ip", description = "listen to address (default '0.0.0.0')")
+    @Parameter(names = "-listen-ip", description = "Address for the Photon server to listen to")
     private String listenIp = "0.0.0.0";
 
-    @Parameter(names = "-cors-any", description = "enable cross-site resource sharing for any origin ((default CORS not supported)")
+    @Parameter(names = "-cors-any", description = "Enable cross-site resource sharing for any origin")
     private boolean corsAnyOrigin = false;
 
-    @Parameter(names = "-cors-origin", description = "enable cross-site resource sharing for the specified origin (default CORS not supported)")
+    @Parameter(names = "-cors-origin", description = "Enable cross-site resource sharing for the specified origin")
     private String corsOrigin = null;
 
     @Parameter(names = "-enable-update-api", description = "Enable the additional endpoint /nominatim-update, which allows to trigger updates from a nominatim database")
     private boolean enableUpdateApi = false;
 
-    @Parameter(names = "-h", description = "show help / usage")
+    @Parameter(names = "-h", description = "Show help / usage")
     private boolean usage = false;
 
     public String[] getLanguages(boolean useDefaultIfEmpty) {

src/main/java/de/komoot/photon/Constants.java

@@ -1,9 +1,7 @@
 package de.komoot.photon;
 
 /**
- * date: 17.10.14
- *
- * @author christoph
+ * Various string constants.
  */
 public class Constants {
     public static final String POSTCODE = "postcode";
@@ -17,14 +15,8 @@ public class Constants {
     public static final String STREET = "street";
     public static final String STATE = "state";
     public static final String COUNTY = "county";
-    public static final String TYPE = "type";
-    public static final String GEOMETRY = "geometry";
-    public static final String PROPERTIES = "properties";
-    public static final String COORDINATES = "coordinates";
     public static final String LAT = "lat";
     public static final String LON = "lon";
-    public static final String FEATURE = "Feature";
-    public static final String POINT = "Point";
     public static final String IMPORTANCE = "importance";
     public static final String OSM_ID = "osm_id";
     public static final String OSM_TYPE = "osm_type";

src/main/java/de/komoot/photon/DatabaseProperties.java

@@ -5,7 +5,7 @@
 /**
  * Class collecting database global properties.
  *
- * The server is responsible for making the data persistent throught the Photon database.
+ * The server is responsible for making the data persistent in the Photon database.
  */
 public class DatabaseProperties {
     private String[] languages = null;
@@ -27,7 +27,7 @@ public String[] getLanguages() {
      *
      * @param languages Array of two-letter language codes.
      *
-     * @return This object for chaining.
+     * @return This object for function chaining.
      */
     public DatabaseProperties setLanguages(String[] languages) {
         this.languages = languages;

src/main/java/de/komoot/photon/Importer.java

@@ -1,20 +1,16 @@
 package de.komoot.photon;
 
 /**
- * interface for bulk imports from a data source like nominatim
- *
- * @author felix
+ * Interface for bulk imports from a data source like nominatim
  */
 public interface Importer {
     /**
-     * a new document was imported
-     *
-     * @param doc
+     * Add a new document to the Photon database.
      */
     public void add(PhotonDoc doc, int objectId);
 
     /**
-     * import is finished
+     * Finish up the import.
      */
     public void finish();
 }

src/main/java/de/komoot/photon/JsonDumper.java

@@ -7,7 +7,7 @@
 import java.io.PrintWriter;
 
 /**
- * useful to create json files that can be used for fast re imports
+ * Importer which writes out the documents in a json-like file.
  */
 public class JsonDumper implements Importer {
     private static final Logger LOGGER = org.slf4j.LoggerFactory.getLogger(JsonDumper.class);

src/main/java/de/komoot/photon/PhotonDoc.java

@@ -9,7 +9,7 @@
 import java.util.*;
 
 /**
- * denormalized doc with all information needed be dumped to elasticsearch
+ * Denormalized document with all information needed for saving in the Photon database.
  */
 public class PhotonDoc {
     private static final Logger LOGGER = org.slf4j.LoggerFactory.getLogger(PhotonDoc.class);

src/main/java/de/komoot/photon/ReverseSearchRequestHandler.java

@@ -17,7 +17,7 @@
 import static spark.Spark.halt;
 
 /**
- * @author svantulden
+ * Webserver route for reverse geocoding requests.
  */
 public class ReverseSearchRequestHandler extends RouteImpl {
     private final ReverseRequestFactory reverseRequestFactory;

src/main/java/de/komoot/photon/SearchRequestHandler.java

@@ -14,6 +14,9 @@
 
 import static spark.Spark.halt;
 
+/**
+ * Webserver route for forward geocoding requests.
+ */
 public class SearchRequestHandler extends RouteImpl {
     private final PhotonRequestFactory photonRequestFactory;
     private final SearchHandler requestHandler;
@@ -38,7 +41,7 @@ public String handle(Request request, Response response) {
 
         List<PhotonResult> results = requestHandler.search(photonRequest);
 
-        // Futher filtering
+        // Further filtering
         results = new StreetDupesRemover(photonRequest.getLanguage()).execute(results);
 
         // Restrict to the requested limit.

src/main/java/de/komoot/photon/Utils.java

@@ -9,9 +9,7 @@
 import java.util.*;
 
 /**
- * helper functions to create convert a photon document to XContentBuilder object / JSON
- *
- * @author christoph
+ * Helper functions to convert a photon document to XContentBuilder object / JSON
  */
 public class Utils {
     public static XContentBuilder convert(PhotonDoc doc, String[] languages, String[] extraTags) throws IOException {

src/main/java/de/komoot/photon/elasticsearch/ElasticResult.java

@@ -8,6 +8,9 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Response object from the ElasticSearch database.
+ */
 public class ElasticResult implements PhotonResult {
     private static final Logger LOGGER = org.slf4j.LoggerFactory.getLogger(ElasticResult.class);
 

src/main/java/de/komoot/photon/elasticsearch/ElasticsearchReverseHandler.java

@@ -49,8 +49,7 @@ public String dumpQuery(ReverseRequest photonRequest) {
     }
 
 
-    private SearchResponse search(QueryBuilder queryBuilder, int limit, Point location,
-                                 boolean locationDistanceSort) {
+    private SearchResponse search(QueryBuilder queryBuilder, int limit, Point location, boolean locationDistanceSort) {
         SearchRequestBuilder builder = client.prepareSearch(PhotonIndex.NAME).setSearchType(SearchType.QUERY_THEN_FETCH)
                 .setQuery(queryBuilder).setSize(limit).setTimeout(queryTimeout);
 

src/main/java/de/komoot/photon/elasticsearch/ElasticsearchSearchHandler.java

@@ -14,7 +14,7 @@
 import java.util.List;
 
 /**
- * Created by Sachin Dole on 2/12/2015.
+ * Execute a forward lookup on a Elasticsearch database.
  */
 public class ElasticsearchSearchHandler implements SearchHandler {
     private final Client client;

src/main/java/de/komoot/photon/elasticsearch/IndexMapping.java

@@ -10,7 +10,7 @@
 import java.io.InputStream;
 
 /**
- * Encapsulates the ES index mapping for the photon index.
+ * ElasticSearch index mapping for the photon index.
  */
 public class IndexMapping {
     private static final Logger LOGGER = org.slf4j.LoggerFactory.getLogger(IndexMapping.class);
@@ -52,12 +52,12 @@ public IndexMapping addLanguages(String[] languages) {
         }
 
         for (String lang : languages) {
-            // create lang-specific json objects
+            // create language-specific json objects
             JSONObject copyToCollectorObject = new JSONObject(copyToCollectorString.replace("{lang}", lang));
             JSONObject nameToCollectorObject = new JSONObject(nameToCollectorString.replace("{lang}", lang));
             JSONObject collectorObject = new JSONObject(collectorString.replace("{lang}", lang));
 
-            // add language specific tags to the collector
+            // add language-specific tags to the collector
             addToCollector("city", propertiesObject, copyToCollectorObject, lang);
             addToCollector("context", propertiesObject, copyToCollectorObject, lang);
             addToCollector("county", propertiesObject, copyToCollectorObject, lang);
@@ -68,7 +68,7 @@ public IndexMapping addLanguages(String[] languages) {
             addToCollector("locality", propertiesObject, copyToCollectorObject, lang);
             addToCollector("name", propertiesObject, nameToCollectorObject, lang);
 
-            // add language specific collector to default for name
+            // add language-specific collector to default for name
             JSONObject name = propertiesObject.optJSONObject("name");
             JSONObject nameProperties = name == null ? null : name.optJSONObject("properties");
             if (nameProperties != null) {
@@ -77,7 +77,7 @@ public IndexMapping addLanguages(String[] languages) {
                 copyToArray.put("name." + lang);
             }
 
-            // add language specific collector
+            // add language-specific collector
             addToCollector("collector", propertiesObject, collectorObject, lang);
         }