Clarify docs on GN rebase_path.

tools/gn/function_rebase_path.cc

 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #include <stddef.h>
 
 #include "tools/gn/build_settings.h"
 #include "tools/gn/filesystem_utils.h"
 #include "tools/gn/functions.h"
 #include "tools/gn/parse_tree.h"
@@ skipping 126 matching lines @@
     "  current directory to be relative to the build directory (which will\n"
     "  be the current directory when executing scripts).\n"
     "\n"
     "  If you want to convert a file path to be source-absolute (that is,\n"
     "  beginning with a double slash like \"//foo/bar\"), you should use\n"
     "  the get_path_info() function. This function won't work because it will\n"
     "  always make relative paths, and it needs to support making paths\n"
     "  relative to the source root, so can't also generate source-absolute\n"
     "  paths without more special-cases.\n"
     "\n"
-    "Arguments:\n"
+    "Arguments\n"
     "\n"
     "  input\n"
     "      A string or list of strings representing file or directory names\n"
     "      These can be relative paths (\"foo/bar.txt\"), system absolute\n"
     "      paths (\"/foo/bar.txt\"), or source absolute paths\n"
     "      (\"//foo/bar.txt\").\n"
     "\n"
     "  new_base\n"
     "      The directory to convert the paths to be relative to. This can be\n"
     "      an absolute path or a relative path (which will be treated\n"
@@ skipping 10 matching lines @@
     "      relative to the current build file. Use \".\" (the default) to\n"
     "      convert paths from the current BUILD-file's directory.\n"
     "\n"
     "Return value\n"
     "\n"
     "  The return value will be the same type as the input value (either a\n"
     "  string or a list of strings). All relative and source-absolute file\n"
     "  names will be converted to be relative to the requested output\n"
     "  System-absolute paths will be unchanged.\n"
     "\n"
+    "  Whether an output path will end in a slash will match whether the\n"
+    "  corresponding input path ends in a slash. It will return \".\" or\n"
+    "  \"./\" (depending on whether the input ends in a slash) to avoid\n"
+    "  returning empty strings. This means if you want a root path\n"
+    "  (\"//\" or \"/\") not ending in a slash, you can add a dot (\"//.\").\n"
+    "\n"
     "Example\n"
     "\n"
     "  # Convert a file in the current directory to be relative to the build\n"
     "  # directory (the current dir when executing compilers and scripts).\n"
     "  foo = rebase_path(\"myfile.txt\", root_build_dir)\n"
     "  # might produce \"../../project/myfile.txt\".\n"
     "\n"
     "  # Convert a file to be system absolute:\n"
     "  foo = rebase_path(\"myfile.txt\")\n"
     "  # Might produce \"D:\\source\\project\\myfile.txt\" on Windows or\n"
@@ skipping 86 matching lines @@
     }
     return result;
   }
 
   *err = Err(function->function(),
              "rebase_path requires a list or a string.");
   return result;
 }
 
 }  // namespace functions