[terminal] IJPL-219717 rename getStartDirectory to getDefaultStartWorkingDirectory; improve its documentation

GitOrigin-RevId: ae194b5e80305ea6c450f65a07daae1bbab6e36a

Author: segrey

plugins/terminal/src/org/jetbrains/plugins/terminal/LocalTerminalCustomizer.java

@@ -10,20 +10,23 @@
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 import org.jetbrains.plugins.terminal.runner.TerminalCustomizerLocalPathTranslator;
+import org.jetbrains.plugins.terminal.startup.MutableShellExecOptions;
+import org.jetbrains.plugins.terminal.startup.ShellExecOptionsCustomizer;
 
 import java.util.Arrays;
 import java.util.List;
 import java.util.Map;
 
 /**
- * @deprecated use {@link org.jetbrains.plugins.terminal.startup.ShellExecOptionsCustomizer} instead
+ * @deprecated use {@link ShellExecOptionsCustomizer} instead
  */
 @Deprecated
 public abstract class LocalTerminalCustomizer {
   public static final ExtensionPointName<LocalTerminalCustomizer> EP_NAME =
     ExtensionPointName.create("org.jetbrains.plugins.terminal.localTerminalCustomizer");
 
   /**
+   * @deprecated use {@link ShellExecOptionsCustomizer#customizeExecOptions(Project, MutableShellExecOptions)} instead
    * May alter the command to be run in terminal and/or adjust starting environment. <p/>
    * Please note that environment variables are local to the remote {@code eelDescriptor}.
    * For example, it should contain {@code /path/to/dir} instead of
@@ -56,6 +59,7 @@ public abstract class LocalTerminalCustomizer {
    * See the {@code bash-integration.bash} script
    * for more information on how to alter the execution process.
    */
+  @Deprecated
   public @NotNull List<String> customizeCommandAndEnvironment(
     @NotNull Project project,
     @Nullable String workingDirectory,
@@ -108,8 +112,10 @@ public String[] customizeCommandAndEnvironment(@NotNull Project project,
   }
 
   /**
+   * @deprecated use {@link ShellExecOptionsCustomizer#getDefaultStartWorkingDirectory(Project)} instead
    * @return path to the directory to run the terminal in or null if default directory should be used
    */
+  @Deprecated
   protected @Nullable String getDefaultFolder(@NotNull Project project) {
     return null;
   }

plugins/terminal/src/org/jetbrains/plugins/terminal/TerminalProjectOptionsProvider.kt

@@ -77,7 +77,7 @@ class TerminalProjectOptionsProvider(val project: Project) : PersistentStateComp
     get() {
       for (customizer in ShellExecOptionsCustomizer.EP_NAME.extensionList) {
         try {
-          val dir = customizer.getStartDirectory(project)
+          val dir = customizer.getDefaultStartWorkingDirectory(project)
           if (dir != null) {
             return dir.toString()
           }

plugins/terminal/src/org/jetbrains/plugins/terminal/startup/ShellExecOptionsCustomizer.kt

@@ -27,14 +27,15 @@ interface ShellExecOptionsCustomizer {
   fun customizeExecOptions(project: Project, shellExecOptions: MutableShellExecOptions) {}
 
   /**
-   * Retrieves the starting directory for the given project.
+   * Customizes the default start working directory for the given project.
+   * It serves as a default value for the "Start directory" field in "Settings | Tools | Terminal".
+   * The value of this field determines the working directory for new shell sessions.
    * 
    * The method can be called on any thread without a read action.
    *
-   * @return the starting directory, or `null` if no directory is specified
-   *         In case of `null`, the default start directory will be used.
+   * @return the starting directory, or `null` to use the default start working directory
    */
-  fun getStartDirectory(project: Project): Path? = null
+  fun getDefaultStartWorkingDirectory(project: Project): Path? = null
 
   companion object {
     @ApiStatus.Internal