PrismSettings: adapt JavaDoc to recent change in settings file location, CHANGELOG.TXT

prism/CHANGELOG.txt

@@ -1,5 +1,24 @@
 This file contains details of the changes in each new version of PRISM.
 
+-----------------------------------------------------------------------------
+Changes since version 4.4
+-----------------------------------------------------------------------------
+
+* Default location of the XPRISM settings file has changed,
+  to avoid cluttering the user's home directory:
+  - On Linux (adhering to XDG Base Directory Specification):
+     $XDG_CONFIG_HOME/prism.settings  (if that environment variable is set)
+     $HOME/.config/prism.settings     (otherwise)
+  - On macOS:
+     $HOME/Library/Preferences/prism.settings
+  - On Windows:
+     .prism in the user's home directory (unchanged from previous location)
+
+  If the settings file already exists in the legacy location
+     $HOME/.prism
+  XPRISM continues to use that location.
+
+
 -----------------------------------------------------------------------------
 Version 4.4 (first released 23/7/2017)
 -----------------------------------------------------------------------------

prism/src/prism/Prism.java

@@ -308,7 +308,7 @@ public class Prism extends PrismComponent implements PrismSettingsListener
 	}
 
 	/**
-	 * Read in PRISM settings from the default file (.prism in user's home directory).
+	 * Read in PRISM settings from the default file (see PrismSettings.getLocationForSettingsFile()).
 	 * If no file exists, attempt to create a new one with default settings.
 	 */
 	public void loadUserSettingsFile()
@@ -318,7 +318,7 @@ public class Prism extends PrismComponent implements PrismSettingsListener
 
 	/**
 	 * Read in PRISM settings from a specified file.
-	 * If the file is null, use the default (.prism in user's home directory).
+	 * If the file is null, use the default (see PrismSettings.getLocationForSettingsFile()).
 	 * If no file exists, attempt to create a new one with default settings.
 	 */
 	public void loadUserSettingsFile(File settingsFile)

prism/src/prism/PrismSettings.java

@@ -627,7 +627,27 @@ public class PrismSettings implements Observer
 			listener.notifySettings(this);
 		}
 	}
-	
+
+	/**
+	 * Get the default location of the settings file.
+	 * <br>
+	 * There is a legacy location (filename '.prism' in the user's
+	 * home directory), and a modern location, which depends on the
+	 * operating system:
+	 * <ul>
+	 * <li>For macOS, the location is $HOME/Library/Preferences/prism.settings</li>
+	 * <li>For Linux, the location depends on the environment variable $XDG_CONFIG_HOME;
+	 * if set, the location is $XDG_CONFIG_HOME/prism.settings;
+	 * if not, it's $HOME/.config/prism.settings</li>
+	 * <li>On Windows, only the legacy location is supported</li>
+	 * </ul>
+	 * <br>
+	 * If the legacy settings file exists, this method returns that location.
+	 * Otherwise, the modern location is returned.
+	 * <br>
+	 * To support different settings files in derived tools (e.g. prism-games),
+	 * the filename is derived from the tool name (see Prism.getToolName()).
+	 */
 	public File getLocationForSettingsFile()
 	{
 		String toolName = Prism.getToolName().toLowerCase();