From 5378d5356067fd26345f9f3e7cecd8901f9c64e5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jaakko=20Ker=C3=A4nen?= <jaakko.keranen@iki.fi>
Date: Mon, 23 Nov 2015 21:38:00 +0200
Subject: [PATCH] Documentation: libdoomsday is a major part of the public API

---
 distrib/autobuild.py                          |  2 +-
 doomsday/apps/api/doomsday.h                  | 17 -----------
 doomsday/apps/client/api.doxy                 | 23 ---------------
 doomsday/apps/libdoomsday/api.doxy            | 29 +++++++++++++++++++
 .../include/doomsday/libdoomsday.h            | 11 ++++++-
 5 files changed, 40 insertions(+), 42 deletions(-)
 delete mode 100644 doomsday/apps/client/api.doxy
 create mode 100644 doomsday/apps/libdoomsday/api.doxy

diff --git a/distrib/autobuild.py b/distrib/autobuild.py
index d305d6ba66..9e5dc5939c 100755
--- a/distrib/autobuild.py
+++ b/distrib/autobuild.py
@@ -453,7 +453,7 @@ def generate_apidoc():
     system_command('wc -l doxyissues-qch.txt')
 
     print >> sys.stderr, "\nPublic API docs..."
-    os.chdir(os.path.join(builder.config.DISTRIB_DIR, '../doomsday/apps/client'))    
+    os.chdir(os.path.join(builder.config.DISTRIB_DIR, '../doomsday/apps/libdoomsday'))    
     system_command('doxygen api.doxy >/dev/null 2>../../doxyissues-api.txt')
     system_command('wc -l ../../doxyissues-api.txt')
 
diff --git a/doomsday/apps/api/doomsday.h b/doomsday/apps/api/doomsday.h
index 36c4b39daa..1e107305df 100644
--- a/doomsday/apps/api/doomsday.h
+++ b/doomsday/apps/api/doomsday.h
@@ -21,23 +21,6 @@
  * 02110-1301 USA</small>
  */
 
-/**
- * @mainpage libdeng API
- *
- * This documentation covers all the functions and data that Doomsday makes
- * available for games and other plugins.
- *
- * @section Overview
- * The documentation has been organized into <a href="modules.html">modules</a>.
- * The primary ones are listed below:
- * - @ref base
- * - @ref console
- * - @ref input
- * - @ref network
- * - @ref resource
- * - @ref render
- */
-
 #ifndef DOOMSDAY_PUBLIC_API_H
 #define DOOMSDAY_PUBLIC_API_H
 
diff --git a/doomsday/apps/client/api.doxy b/doomsday/apps/client/api.doxy
deleted file mode 100644
index 2f95f0e855..0000000000
--- a/doomsday/apps/client/api.doxy
+++ /dev/null
@@ -1,23 +0,0 @@
-# Public API documentation for Doomsday and liblegacy
-@INCLUDE = ../../doomsday.doxy
-
-PROJECT_NAME            = "Doomsday and liblegacy"
-PROJECT_NUMBER          = 2.0
-PROJECT_BRIEF           = "Public API"
-PROJECT_LOGO            = ../../doc/apidoc-logo.png
-HTML_STYLESHEET         = ../../doxygen.css
-OUTPUT_DIRECTORY        = ../../apidoc/api/
-
-INPUT                   = ../api
-PREDEFINED              = __DOOMSDAY__ \
-                          "DENG_API_TYPEDEF(Name)=typedef struct de_api_##Name##_s" \
-                          "DENG_API_T(Name)=de_api_##Name##_t" \
-                          "DENG_DECLARE_API(Name)=DENG_API_T(Name) _api_##Name"
-
-INCLUDED_BY_GRAPH       = YES
-REFERENCED_BY_RELATION  = NO
-OPTIMIZE_OUTPUT_FOR_C   = NO
-MACRO_EXPANSION         = YES
-EXPAND_ONLY_PREDEF      = YES
-EXTRACT_PRIVATE         = NO
-INTERNAL_DOCS           = NO
diff --git a/doomsday/apps/libdoomsday/api.doxy b/doomsday/apps/libdoomsday/api.doxy
new file mode 100644
index 0000000000..4519879a08
--- /dev/null
+++ b/doomsday/apps/libdoomsday/api.doxy
@@ -0,0 +1,29 @@
+# Public API documentation for libdoomsday
+@INCLUDE = ../../doomsday.doxy
+
+PROJECT_NAME            = "Doomsday Engine"
+PROJECT_NUMBER          = 2.0
+PROJECT_BRIEF           = "Shared functionality for client, server and plugins"
+PROJECT_LOGO            = ../../doc/apidoc-logo.png
+HTML_STYLESHEET         = ../../doxygen.css
+OUTPUT_DIRECTORY        = ../../apidoc/api/
+
+INPUT                   = ../api include src
+PREDEFINED              = __cplusplus __LIBDOOMSDAY__ \
+                          "LIBDOOMSDAY_PUBLIC=" \
+                          "DENG2_PIMPL(ClassName)=typedef ClassName Public; struct ClassName::Instance : public de::Private<ClassName>" \
+                          "DENG2_PIMPL_NOREF(C)=struct C::Instance : public de::IPrivate" \
+                          "DENG_GUI_PIMPL(C)=struct C::public de::GuiWidgetPrivate<C>" \
+                          "DENG2_PRIVATE(Var)=struct Instance; Instance *Var;" \
+                          "DENG2_ERROR(N)=class N : public de::Error {};" \
+                          "DENG2_SUB_ERROR(B,N)=class N : public B {};" \
+                          "DENG2_OBSERVES(C,A)=public C::I##Audience##Observer" \
+                          "DENG2_DEFINE_AUDIENCE2(Name,Method)=class I##Name##Observer { public: virtual ~I##Name##Observer() {} virtual Method = 0; }; typedef de::Observers<I##Name##Observer> Name##Audience; Name##Audience &audienceFor##Name(); Name##Audience const &audienceFor##Name() const;"
+
+INCLUDED_BY_GRAPH       = YES
+REFERENCED_BY_RELATION  = NO
+OPTIMIZE_OUTPUT_FOR_C   = NO
+MACRO_EXPANSION         = YES
+EXPAND_ONLY_PREDEF      = YES
+EXTRACT_PRIVATE         = NO
+INTERNAL_DOCS           = NO
diff --git a/doomsday/apps/libdoomsday/include/doomsday/libdoomsday.h b/doomsday/apps/libdoomsday/include/doomsday/libdoomsday.h
index e6f8215637..0790746aa4 100644
--- a/doomsday/apps/libdoomsday/include/doomsday/libdoomsday.h
+++ b/doomsday/apps/libdoomsday/include/doomsday/libdoomsday.h
@@ -13,12 +13,21 @@
  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
  * General Public License for more details. You should have received a copy of
  * the GNU Lesser General Public License along with this program; if not, see:
- * http://www.gnu.org/licenses</small> 
+ * http://www.gnu.org/licenses</small>
  */
 
 #ifndef LIBDOOMSDAY_MAIN_H
 #define LIBDOOMSDAY_MAIN_H
 
+/**
+ * @mainpage Doomsday Engine
+ *
+ * This documentation is for the shared @em libdoomsday library that is the
+ * common foundation for the Client, Server, and plugins. Additionally, the
+ * client/server runtime API is included here, because it is made available
+ * for plugins to access at runtime.
+ */
+
 #include <de/c_wrapper.h>
 
 /*