Add code snippets to FileHandle.md

Add semihosting and SWO examples to mbed_override_console() by applying changes from PR #1063

Author: Amanda Butler

docs/api/platform/FileHandle.md

@@ -69,19 +69,20 @@ If a target has serial support, by default a serial port is used for the console
 The target can override this by providing `mbed::mbed_target_override_console` to specify an alternative `FileHandle`. For example, a target using SWO might have:
 
 ```
-    namespace mbed
+namespace mbed
+{
+    FileHandle *mbed_target_override_console(int)
     {
-        FileHandle *mbed_target_override_console(int)
-        {
-            static SerialWireOutput swo;
-            return &swo;
-        }
+        // SerialWireOutput
+        static SerialWireOutput swo;
+        return &swo;
     }
+}
 ```
 
 Then any program using `printf` on that target sends its output over the SWO, rather than serial.
 
-Because targets can redirect the console in this way, portable applications should not use constructs like `Serial(USBTX, USBRX)`, assuming that this will access the console. Instead they should use `stdin`/`stdout`/`stderr` or `STDIN_FILENO`/`STDOUT_FILENO`/`STDERR_FILENO`.
+Because targets can redirect the console in this way, portable applications should not use constructs such as `Serial(USBTX, USBRX)`, assuming that this will access the console. Instead they should use `stdin`/`stdout`/`stderr` or `STDIN_FILENO`/`STDOUT_FILENO`/`STDERR_FILENO`.
 
 ```
     // Don't do:
@@ -92,13 +93,47 @@ Because targets can redirect the console in this way, portable applications shou
     printf("Hello!\n");  // assume platform.stdio-convert-newlines is true
 ```
 
-Beyond the target-specific override, an application can override the target's default behavior itself by providing `mbed::mbed_override_console`.
+Beyond the target-specific override, an application can override the target's default behavior itself by providing `mbed::mbed_override_console`. Below are two examples that show how you can redirect the console to a debugger using semihosting or another application-specific serial port:
+
+```
+namespace mbed
+{
+    FileHandle *mbed_override_console(int fileno)
+    {
+        // Semihosting allows "virtual" console access through a debugger.
+        static LocalFileSystem fs("host");
+        if (fileno == STDIN_FILENO) {
+            static FileHandle *in_terminal;
+            static int in_open_result = fs.open(&in_terminal, ":tt", O_RDONLY);
+            return in_terminal;
+        } else {
+            static FileHandle *out_terminal;
+            static int out_open_result = fs.open(&out_terminal, ":tt", O_WRONLY);
+            return out_terminal;
+        }
+    }
+}
+```
+
+The application can redirect the console to a different serial port if you need the default port for another use:
+
+```
+namespace
+{
+    FileHandle *mbed_override_console(int)
+    {
+        static UARTSerial uart(PA_0, PA_1);
+        return &uart;
+    }
+}
+```
+
+Alternatively, an application could use the standard C `freopen` function to redirect `stdout` to a named file or device while running. However there is no `fdreopen` analog to redirect to an unnamed device by file descriptor or `FileHandle` pointer. 
 
-Alternatively, an application could use the standard C `freopen` function to redirect `stdout` to a named file or device while running. However there is no `fdreopen` analogue to redirect to an unnamed device by file descriptor or `FileHandle` pointer.
+### Polling and nonblocking
 
-## Polling and nonblocking
+By default, `FileHandle`s conventionally block until a `read` or `write` operation completes. This is the only behavior supported by normal `File`s, and is expected by the C library's `stdio` functions.
 
-By default `FileHandle`s conventionally block until a `read` or `write` operation completes. This is the only behavior supported by normal `File`s, and is expected by the C library's `stdio` functions.
 
 Device-type `FileHandle`s, such as `UARTSerial`, are expected to also support nonblocking operation, which permits the `read` and `write` calls to return immediately when unable to transfer data. Please see the API reference pages of these functions for more information.