4 files changed, 83 insertions, 17 deletions
diff --git a/lib/stdlib/doc/src/c.xml b/lib/stdlib/doc/src/c.xml
index 55a77d1bc5..7666699183 100644
--- a/lib/stdlib/doc/src/c.xml
+++ b/lib/stdlib/doc/src/c.xml
@@ -52,13 +52,27 @@
     <func>
       <name name="c" arity="1"/>
       <name name="c" arity="2"/>
-      <fsummary>Compile and load code in a file.</fsummary>
+      <name name="c" arity="3"/>
+      <fsummary>Compile and load a file or module.</fsummary>
       <desc>
-        <p>Compiles and then purges and loads the code for a file.
-          <c><anno>Options</anno></c> defaults to <c>[]</c>. Compilation is
-          equivalent to:</p>
-        <code type="none">
-compile:file(<anno>File</anno>, <anno>Options</anno> ++ [report_errors, report_warnings])</code>
+        <p>Compiles and then purges and loads the code for a module.
+          <c><anno>Module</anno></c> can be either a module name or a source
+          file path, with or without <c>.erl</c> extension.
+          <c><anno>Options</anno></c> defaults to <c>[]</c>.</p>
+        <p>If <c><anno>Module</anno></c> is an atom and is not the path of a
+          source file, then the code path is searched to locate the object
+          file for the module and extract its original compiler options and
+          source path. If the source file is not found in the original
+          location, <seealso
+          marker="filelib#find_source/1"><c>filelib:find_source/1</c></seealso>
+          is used to search for it relative to the directory of the object
+          file.</p>
+        <p>The source file is compiled with the the original
+          options appended to the given <c><anno>Options</anno></c>, the
+          output replacing the old object file if and only if compilation
+          succeeds. A function <c><anno>Filter</anno></c> can be specified
+          for removing elements from from the original compiler options
+          before the new options are added.</p>
         <p>Notice that purging the code means that any processes
           lingering in old code for the module are killed without
           warning. For more information, see <c>code/3</c>.</p>
diff --git a/lib/stdlib/doc/src/filelib.xml b/lib/stdlib/doc/src/filelib.xml
index 7c6380ce28..ad73fc254a 100644
--- a/lib/stdlib/doc/src/filelib.xml
+++ b/lib/stdlib/doc/src/filelib.xml
@@ -60,6 +60,12 @@
     <datatype>
       <name name="filename_all"/>
     </datatype>
+    <datatype>
+      <name name="find_file_rule"/>
+    </datatype>
+    <datatype>
+      <name name="find_source_rule"/>
+    </datatype>
   </datatypes>
 
   <funcs>
@@ -226,7 +232,51 @@ filelib:wildcard("lib/**/*.{erl,hrl}")</code>
           directory.</p>
       </desc>
     </func>
+
+    <func>
+      <name name="find_file" arity="2"/>
+      <name name="find_file" arity="3"/>
+      <fsummary>Find a file relative to a given directory.</fsummary>
+      <desc>
+        <p>Looks for a file of the given name by applying suffix rules to
+        the given directory path. For example, a rule <c>{"ebin", "src"}</c>
+        means that if the directory path ends with <c>"ebin"</c>, the
+        corresponding path ending in <c>"src"</c> should be searched.</p>
+        <p>If <c><anno>Rules</anno></c> is left out or is an empty list, the
+        default system rules are used. See also the Kernel application
+        parameter <seealso
+        marker="kernel:kernel_app#source_search_rules"><c>source_search_rules</c></seealso>.</p>
+      </desc>
+    </func>
+    <func>
+      <name name="find_source" arity="1"/>
+      <fsummary>Find the source file for a given object file.</fsummary>
+      <desc>
+        <p>Equivalent to <c>find_source(Base, Dir)</c>, where <c>Dir</c> is
+        <c>filename:dirname(<anno>FilePath</anno>)</c> and <c>Base</c> is
+        <c>filename:basename(<anno>FilePath</anno>)</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name name="find_source" arity="2"/>
+      <name name="find_source" arity="3"/>
+      <fsummary>Find a source file relative to a given directory.</fsummary>
+      <desc>
+        <p>Applies file extension specific rules to find the source file for
+        a given object file relative to the object directory. For example,
+        for a file with the extension <c>.beam</c>, the default rule is to
+        look for a file with a corresponding extension <c>.erl</c> by
+        replacing the suffix <c>"ebin"</c> of the object directory path with
+        <c>"src"</c>.
+        The file search is done through <seealso
+        marker="#find_file/3"><c>find_file/3</c></seealso>. The directory of
+        the object file is always tried before any other directory specified
+        by the rules.</p>
+        <p>If <c><anno>Rules</anno></c> is left out or is an empty list, the
+        default system rules are used. See also the Kernel application
+        parameter <seealso
+        marker="kernel:kernel_app#source_search_rules"><c>source_search_rules</c></seealso>.</p>
+      </desc>
+    </func>
   </funcs>
 </erlref>
-
-
diff --git a/lib/stdlib/doc/src/filename.xml b/lib/stdlib/doc/src/filename.xml
index 2a413835d0..7acef51ca1 100644
--- a/lib/stdlib/doc/src/filename.xml
+++ b/lib/stdlib/doc/src/filename.xml
@@ -356,10 +356,12 @@ true
         <p>Finds the source filename and compiler options for a module.
           The result can be fed to <seealso marker="compiler:compile#file/2">
           <c>compile:file/2</c></seealso> to compile the file again.</p>
-        <warning><p>It is not recommended to use this function. If possible,
-          use the <seealso marker="beam_lib"><c>beam_lib(3)</c></seealso>
-          module to extract the abstract code format from the Beam file and
-          compile that instead.</p></warning>
+        <warning>
+          <p>This function is deprecated. Use <seealso marker="filelib#find_source/1">
+            <c>filelib:find_source/1</c></seealso> instead for finding source files.</p>
+          <p>If possible, use the <seealso marker="beam_lib"><c>beam_lib(3)</c></seealso>
+          module to extract the compiler options and the abstract code
+          format from the Beam file and compile that instead.</p></warning>
         <p>Argument <c><anno>Beam</anno></c>, which can be a string or an atom,
           specifies either the module name or the path to the source
           code, with or without extension <c>".erl"</c>. In either
diff --git a/lib/stdlib/doc/src/shell.xml b/lib/stdlib/doc/src/shell.xml
index d6e8036d4e..f52bc39deb 100644
--- a/lib/stdlib/doc/src/shell.xml
+++ b/lib/stdlib/doc/src/shell.xml
@@ -165,12 +165,12 @@
       <item>
         <p>Evaluates <c>shell_default:help()</c>.</p>
       </item>
-      <tag><c>c(File)</c></tag>
+      <tag><c>c(Mod)</c></tag>
       <item>
-        <p>Evaluates <c>shell_default:c(File)</c>. This compiles
-          and loads code in <c>File</c> and purges old versions of
-          code, if necessary. Assumes that the file and module names
-          are the same.</p>
+        <p>Evaluates <c>shell_default:c(Mod)</c>. This compiles and
+          loads the module <c>Mod</c> and purges old versions of the
+          code, if necessary. <c>Mod</c> can be either a module name or a
+          a source file path, with or without <c>.erl</c> extension.</p>
       </item>
       <tag><c>catch_exception(Bool)</c></tag>
       <item>