Platform: more documentation updates.

src/Magnum/Platform/AbstractXApplication.h

@@ -88,7 +88,10 @@ class AbstractXApplication {
 
         /**
          * @brief Execute main loop
-         * @return Value for returning from `main()`.
+         * @return Value for returning from `main()`
+         *
+         * See @ref MAGNUM_GLXAPPLICATION_MAIN() or
+         * @ref MAGNUM_XEGLAPPLICATION_MAIN() for usage information.
          */
         int exec();
 

src/Magnum/Platform/GlutApplication.h

@@ -132,7 +132,12 @@ class GlutApplication {
         /** @brief Moving is not allowed */
         GlutApplication& operator=(GlutApplication&&) = delete;
 
-        /** @copydoc Sdl2Application::exec() */
+        /**
+         * @brief Execute main loop
+         * @return Value for returning from `main()`
+         *
+         * See @ref MAGNUM_GLUTAPPLICATION_MAIN() for usage information.
+         */
         int exec() {
             glutMainLoop();
             return 0;
@@ -560,9 +565,10 @@ class GlutApplication::MouseMoveEvent: public GlutApplication::InputEvent {
 @brief Entry point for GLUT-based applications
 @param className Class name
 
-Can be with @ref Magnum::Platform::GlutApplication "Platform::GlutApplication"
-subclasses used as equivalent to the following code to achieve better
-portability, see @ref portability-applications for more information.
+See @ref Magnum::Platform::GlutApplication "Platform::GlutApplication" for
+usage information. This macro abstracts out platform-specific entry point code
+and is equivalent to the following, see @ref portability-applications for more
+information.
 @code
 int main(int argc, char** argv) {
     className app({argc, argv});

src/Magnum/Platform/GlxApplication.h

@@ -92,9 +92,10 @@ class GlxApplication: public AbstractXApplication {
 @brief Entry point for GLX-based applications
 @param className Class name
 
-Can be used with @ref Magnum::Platform::GlxApplication "Platform::GlxApplication"
-subclasses as equivalent to the following code to achieve better portability,
-see @ref portability-applications for more information.
+See @ref Magnum::Platform::GlxApplication "Platform::GlxApplication" for usage
+information. This macro abstracts out platform-specific entry point code and is
+equivalent to the following, see @ref portability-applications for more
+information.
 @code
 int main(int argc, char** argv) {
     className app({argc, argv});

src/Magnum/Platform/NaClApplication.h

@@ -750,7 +750,9 @@ namespace Implementation {
 @brief Entry point for NaCl application
 @param application  Application class name
 
-See @ref Magnum::Platform::NaClApplication "Platform::NaClApplication" and
+See @ref Magnum::Platform::NaClApplication "Platform::NaClApplication" for
+usage information. This macro abstracts out platform-specific entry point code
+(the classic `main()` function cannot be used in NaCl). See
 @ref portability-applications for more information. When no other application
 header is included this macro is also aliased to `MAGNUM_APPLICATION_MAIN()`.
 */

src/Magnum/Platform/Sdl2Application.h

@@ -232,7 +232,9 @@ class Sdl2Application {
 
         /**
          * @brief Execute main loop
-         * @return Value for returning from `main()`.
+         * @return Value for returning from `main()`
+         *
+         * See @ref MAGNUM_SDL2APPLICATION_MAIN() for usage information.
          */
         int exec();
 
@@ -876,9 +878,10 @@ class Sdl2Application::MouseMoveEvent: public Sdl2Application::InputEvent {
 @brief Entry point for SDL2-based applications
 @param className Class name
 
-Can be used with @ref Magnum::Platform::Sdl2Application "Platform::Sdl2Application"
-subclasses as equivalent to the following code to achieve better portability,
-see @ref portability-applications for more information.
+See @ref Magnum::Platform::Sdl2Application "Platform::Sdl2Application" for
+usage information. This macro abstracts out platform-specific entry point code
+and is equivalent to the following, see @ref portability-applications for more
+information.
 @code
 int main(int argc, char** argv) {
     className app({argc, argv});

src/Magnum/Platform/WindowlessGlxApplication.h

@@ -130,7 +130,9 @@ class WindowlessGlxApplication {
 
         /**
          * @brief Execute application
-         * @return Value for returning from `main()`.
+         * @return Value for returning from `main()`
+         *
+         * See @ref MAGNUM_WINDOWLESSAPPLICATION_MAIN() for usage information.
          */
         virtual int exec() = 0;
 
@@ -174,9 +176,10 @@ class WindowlessGlxApplication::Configuration {
 @brief Entry point for windowless GLX application
 @param className Class name
 
-Can be used with @ref Magnum::Platform::WindowlessGlxApplication "Platform::WindowlessGlxApplication"
-subclasses as equivalent to the following code to achieve better portability,
-see @ref portability-applications for more information.
+See @ref Magnum::Platform::WindowlessGlxApplication "Platform::WindowlessGlxApplication"
+for usage information. This macro abstracts out platform-specific entry point
+code and is equivalent to the following, see @ref portability-applications for
+more information.
 @code
 int main(int argc, char** argv) {
     className app({argc, argv});

src/Magnum/Platform/WindowlessNaClApplication.h

@@ -133,9 +133,17 @@ class WindowlessNaClApplication: public pp::Instance, public pp::Graphics3DClien
         /** @brief Moving is not allowed */
         WindowlessNaClApplication& operator=(WindowlessNaClApplication&&) = delete;
 
+    #ifdef DOXYGEN_GENERATING_OUTPUT
+    protected:
+    #else
+    private:
+    #endif
         /**
          * @brief Execute application
-         * @return Value for returning from `main()`.
+         * @return Value for returning from `main()`
+         *
+         * This function is not meant to be called from user code, see
+         * @ref MAGNUM_WINDOWLESSNACLAPPLICATION_MAIN() for usage information.
          */
         virtual int exec() = 0;
 
@@ -199,8 +207,10 @@ namespace Implementation {
 @param application  Application class name
 
 See @ref Magnum::Platform::WindowlessNaClApplication "Platform::WindowlessNaClApplication"
-and @ref portability-applications for more information. When no other
-windowless application header is included this macro is also aliased to
+for usage information. This macro abstracts out platform-specific entry point
+code (the classic `main()` function cannot be used in NaCl). See
+@ref portability-applications for more information. When no other windowless
+application header is included this macro is also aliased to
 `MAGNUM_WINDOWLESSAPPLICATION_MAIN()`.
 */
 /* look at that insane placement of __attribute__. WTF. */

src/Magnum/Platform/XEglApplication.h

@@ -92,9 +92,10 @@ class XEglApplication: public AbstractXApplication {
 @brief Entry point for X/EGL-based applications
 @param className Class name
 
-Can be used with @ref Magnum::Platform::XEglApplication "Platform::XEglApplication"
-subclasses as equivalent to the following code to achieve better portability,
-see @ref portability-applications for more information.
+See @ref Magnum::Platform::XEglApplication "Platform::XEglApplication" for
+usage information. This macro abstracts out platform-specific entry point code
+and is equivalent to the following, see @ref portability-applications for more
+information.
 @code
 int main(int argc, char** argv) {
     className app({argc, argv});