Merge branch 'sv/sys_get_status' into ccase/r13b04_dev

* sv/sys_get_status:
  Teach sys:get_status/1,2 to call Mod:format_status/2
  gen_fsm: Fix format_status/2 to handle Pids

OTP-8324  The ability for the gen_server and gen_fsm callback modules to
          format their own state for display under the sys:get_status/1,2
          calls has been restored and documented. (Thanks to Steve
          Vinoski.)

3 files changed, 83 insertions, 15 deletions

diff --git a/lib/stdlib/doc/src/gen_fsm.xml b/lib/stdlib/doc/src/gen_fsm.xml
index f5d8b9bb48..739cd0bffd 100644
--- a/lib/stdlib/doc/src/gen_fsm.xml
+++ b/lib/stdlib/doc/src/gen_fsm.xml
@@ -729,6 +729,36 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
           updated internal data.</p>
       </desc>
     </func>
+    <func>
+      <name>Module:format_status(normal, [PDict, StateData]) -> Status</name>
+      <fsummary>Optional function for providing a term describing the
+        current gen_fsm status.</fsummary>
+      <type>
+        <v>PDict = [{Key, Value}]</v>
+        <v>StateData = term()</v>
+        <v>Status = [term()]</v>
+      </type>
+      <desc>
+        <p><em>This callback is optional, so callback modules need not
+          export it. The gen_fsm module provides a default
+          implementation of this function that returns the callback
+          module state data.</em></p>
+        <p>This function is called by a gen_fsm process when one
+          of <seealso marker="sys#get_status/1">sys:get_status/1,2</seealso>
+          is invoked to get the gen_fsm status. A callback module
+          wishing to customise the <c>sys:get_status/1,2</c> return
+          value exports an instance of <c>format_status/2</c> that
+          returns a term describing the current status of the
+          gen_fsm.</p>
+        <p><c>PDict</c> is the current value of the gen_fsm's
+          process dictionary.</p>
+        <p><c>StateData</c> is the internal state data of the
+          gen_fsm.</p>
+        <p>The function should return <c>Status</c>, a list of one or
+          more terms that customise the details of the current state
+          and status of the gen_fsm.</p>
+      </desc>
+    </func>
   </funcs>
 
   <section>
diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml
index 8496802259..30c04d1d52 100644
--- a/lib/stdlib/doc/src/gen_server.xml
+++ b/lib/stdlib/doc/src/gen_server.xml
@@ -598,6 +598,35 @@ gen_server:abcast     -----> Module:handle_cast/2
         <p>The function should return the updated internal state.</p>
       </desc>
     </func>
+    <func>
+      <name>Module:format_status(normal, [PDict, State]) -> Status</name>
+      <fsummary>Optional function for providing a term describing the
+        current gen_server status.</fsummary>
+      <type>
+        <v>PDict = [{Key, Value}]</v>
+        <v>State = term()</v>
+        <v>Status = [term()]</v>
+      </type>
+      <desc>
+        <p><em>This callback is optional, so callback modules need not
+          export it. The gen_server module provides a default
+          implementation of this function that returns the callback
+          module state.</em></p>
+        <p>This function is called by a gen_server process when one
+          of <seealso marker="sys#get_status/1">sys:get_status/1,2</seealso>
+          is invoked to get the gen_server status. A callback module
+          wishing to customise the <c>sys:get_status/1,2</c> return
+          value exports an instance of <c>format_status/2</c> that
+          returns a term describing the current status of the
+          gen_server.</p>
+        <p><c>PDict</c> is the current value of the gen_server's
+          process dictionary.</p>
+        <p><c>State</c> is the internal state of the gen_server.</p>
+        <p>The function should return <c>Status</c>, a list of one or
+          more terms that customise the details of the current state
+          and status of the gen_server.</p>
+      </desc>
+    </func>
   </funcs>
 
   <section>
diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml
index a395a8a415..10ead62073 100644
--- a/lib/stdlib/doc/src/sys.xml
+++ b/lib/stdlib/doc/src/sys.xml
@@ -4,23 +4,21 @@
 <erlref>
   <header>
     <copyright>
-      <year>1996</year>
-      <year>2007</year>
-      <holder>Ericsson AB, All Rights Reserved</holder>
+      <year>1996</year><year>2009</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
-  The contents of this file are subject to the Erlang Public License,
-  Version 1.1, (the "License"); you may not use this file except in
-  compliance with the License. You should have received a copy of the
-  Erlang Public License along with this software. If not, it can be
-  retrieved online at http://www.erlang.org/.
-
-  Software distributed under the License is distributed on an "AS IS"
-  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
-  the License for the specific language governing rights and limitations
-  under the License.
-
-  The Initial Developer of the Original Code is Ericsson AB.
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
     </legalnotice>
 
     <title>sys</title>
@@ -237,6 +235,17 @@
       </type>
       <desc>
         <p>Gets the status of the process.</p>
+        <p>The value of <c>Misc</c> varies for different types of
+          processes. For example, a <c>gen_server</c> process returns
+          the callback module's state, and a <c>gen_fsm</c> process
+          returns information such as its current state name. Callback
+          modules for <c>gen_server</c> and <c>gen_fsm</c> can also
+          customise the value of <c>Misc</c> by exporting
+          a <c>format_status/2</c> function that contributes
+          module-specific information;
+          see <seealso marker="gen_server#format_status/2">gen_server:format_status/2</seealso>
+          and <seealso marker="gen_fsm#format_status/2">gen_fsm:format_status/2</seealso>
+          for more details.</p>
       </desc>
     </func>
     <func>