From 0df97b48134314c8bbd58a0e4d4b1dc9070d0b59 Mon Sep 17 00:00:00 2001
From: Marco Antognini <antognini.marco@gmail.com>
Date: Sun, 6 Sep 2015 13:02:34 +0200
Subject: [PATCH] Updated platform-specific handle documentation

---
 doc/doxyfile.in                      |  2 +-
 include/SFML/Window/Window.hpp       |  8 ++----
 include/SFML/Window/WindowHandle.hpp | 39 +++++++++++++++++++++++-----
 3 files changed, 36 insertions(+), 13 deletions(-)

diff --git a/doc/doxyfile.in b/doc/doxyfile.in
index 75d238f9c..f8be2c411 100644
--- a/doc/doxyfile.in
+++ b/doc/doxyfile.in
@@ -301,7 +301,7 @@ EXTENSION_MAPPING      =
 # case of backward compatibilities issues.
 # The default value is: YES.
 
-MARKDOWN_SUPPORT       = NO
+MARKDOWN_SUPPORT       = YES
 
 # When enabled doxygen tries to link words that correspond to documented
 # classes, or namespaces to their corresponding documentation. Such a link can
diff --git a/include/SFML/Window/Window.hpp b/include/SFML/Window/Window.hpp
index 44f075226..41fc0a9a8 100644
--- a/include/SFML/Window/Window.hpp
+++ b/include/SFML/Window/Window.hpp
@@ -98,8 +98,7 @@ public:
     /// advanced OpenGL context settings such as antialiasing,
     /// depth-buffer bits, etc.
     ///
-    /// \param handle   Platform-specific handle of the control (\a HWND on
-    ///                 Windows, \a %Window on Linux/FreeBSD, \a NSWindow on OS X)
+    /// \param handle   Platform-specific handle of the control
     /// \param settings Additional settings for the underlying OpenGL context
     ///
     ////////////////////////////////////////////////////////////
@@ -143,8 +142,7 @@ public:
     /// advanced OpenGL context settings such as antialiasing,
     /// depth-buffer bits, etc.
     ///
-    /// \param handle   Platform-specific handle of the control (\a HWND on
-    ///                 Windows, \a %Window on Linux/FreeBSD, \a NSWindow on OS X)
+    /// \param handle   Platform-specific handle of the control
     /// \param settings Additional settings for the underlying OpenGL context
     ///
     ////////////////////////////////////////////////////////////
@@ -459,8 +457,6 @@ public:
     /// You shouldn't need to use this function, unless you have
     /// very specific stuff to implement that SFML doesn't support,
     /// or implement a temporary workaround until a bug is fixed.
-    /// The type is \a HWND on Windows, \a %Window on Linux/FreeBSD
-    /// and \a NSWindow on OS X.
     ///
     /// \return System handle of the window
     ///
diff --git a/include/SFML/Window/WindowHandle.hpp b/include/SFML/Window/WindowHandle.hpp
index 9da3042ca..0f0f9ef7f 100644
--- a/include/SFML/Window/WindowHandle.hpp
+++ b/include/SFML/Window/WindowHandle.hpp
@@ -37,10 +37,6 @@
 
 namespace sf
 {
-////////////////////////////////////////////////////////////
-/// Define a low-level window handle type, specific to
-/// each platform
-////////////////////////////////////////////////////////////
 #if defined(SFML_SYSTEM_WINDOWS)
 
     // Window handle is HWND (HWND__*) on Windows
@@ -53,7 +49,7 @@ namespace sf
 
 #elif defined(SFML_SYSTEM_MACOS)
 
-    // Window handle is NSWindow (void*) on Mac OS X - Cocoa
+    // Window handle is NSWindow or NSView (void*) on Mac OS X - Cocoa
     typedef void* WindowHandle;
 
 #elif defined(SFML_SYSTEM_IOS)
@@ -63,12 +59,43 @@ namespace sf
 
 #elif defined(SFML_SYSTEM_ANDROID)
 
-    // Window handle is ANativeWindow (void*) on Android
+    // Window handle is ANativeWindow* (void*) on Android
     typedef void* WindowHandle;
 
+#elif defined(SFML_DOXYGEN)
+
+    // Define typedef symbol so that Doxygen can attach some documentation to it
+    typedef "platform–specific" WindowHandle;
+
 #endif
 
 } // namespace sf
 
 
 #endif // SFML_WINDOWHANDLE_HPP
+
+////////////////////////////////////////////////////////////
+/// \typedef sf::WindowHandle
+/// \ingroup window
+///
+/// Define a low-level window handle type, specific to
+/// each platform.
+///
+/// Platform        | Type
+/// ----------------|------------------------------------------------------------
+/// Windows         | \p HWND
+/// Linux/FreeBSD   | \p %Window
+/// Mac OS X        | either \p NSWindow* or \p NSView*, disguised as \p void*
+/// iOS             | \p UIWindow*
+/// Android         | \p ANativeWindow*
+///
+/// \par Mac OS X Specification
+///
+/// On Mac OS X, a sf::Window can be created either from an
+/// existing \p NSWindow* or an \p NSView*. When the window
+/// is created from a window, SFML will use its content view
+/// as the OpenGL area. sf::Window::getSystemHandle() will
+/// return the handle that was used to create the window,
+/// which is a \p NSWindow* by default.
+///
+////////////////////////////////////////////////////////////