Note that server directories are for information only.

These variables often contain information about how the server is set up, and the server may not expose this information for security or because it does not apply (for example, config may come from a database, not a filesystem path). We need to be very clear to people using these paths that they are not to be relied on in code.

See #5313 and #5402 for more context.

Fixes #5313

packages/application/src/frontend.ts

@@ -276,7 +276,20 @@ export namespace JupyterFrontEnd {
     };
 
     /**
-     * The local directories used by the application.
+     * The server directories used by the application, for user information
+     * only.
+     *
+     * #### Notes
+     * These are for user information and user interface hints only and should
+     * not be relied on in code. A server may set these to empty strings if it
+     * does not want to expose this information.
+     *
+     * Examples of appropriate use include displaying a help dialog for a user
+     * listing the paths, or a tooltip in a filebrowser displaying the server
+     * root. Examples of inapproriate use include using one of these paths in a
+     * terminal command, generating code using these paths, or using one of
+     * these paths in a request to the server (it would be better to write a
+     * server extension to handle these cases).
      */
     readonly directories: {
       readonly appSettings: string;