Api documentation

README.md

@@ -9,6 +9,8 @@ protocol and data collection framework that will work as a standalone
 server. Once built, you only need to specify the XML description of
 the devices and the location of the adapter.
 
+**NOTE: This version cannot currently be built on Windows XP since there is currently no support for the XP toolchain and C++ 17.**
+
 Pre-built binary releases for Windows are available from [Releases](https://github.com/mtconnect/cppagent/releases) for those who do not want to build the agent themselves. For *NIX users, you will need libxml2, cppunit, and cmake as well as build essentials.
 
 Version 2.1.0 Added MQTT Sink, Agent Restart and new JSON format (version 2)
@@ -769,7 +771,6 @@ The following parameters must be present to enable https requests. If there is n
         not found the default device if only one device is specified
         in the devices file.
 
-
     * `Host` - The host the adapter is located on.
 
         *Default*: localhost
@@ -849,12 +850,16 @@ The following parameters must be present to enable https requests. If there is n
 
         *Default*: Top Level Setting
 
-	* `ShdrVersion` - Specifies the SHDR protocol version used by the adapter. When greater than one (1), allows multiple complex observations, like `Condition` and `Message` on the same line. If it equials one (1), then any observation requiring more than a key/value pair need to be on separate lines. Applies to only this adapter.
+    * `ShdrVersion` - Specifies the SHDR protocol version used by the adapter. When greater than one 
+      (1), allows  multiple complex observations, like `Condition` and `Message` on the same line. 
+      If it equials one (1), then any observation requiring more than a key/value pair need to be on 
+      separate lines. Applies to only this adapter.
 
 	    *Default*: 1
 
-	* `SuppressIPAddress` - Suppress the Adapter IP Address and port when creating the Agent Device ids and names.
-		*Default*: false
+    * `SuppressIPAddress` - Suppress the Adapter IP Address and port when creating the Agent Device ids and names.
+
+        *Default*: false
 
 
 ### Agent Adapter Configuration

agent_lib/CMakeLists.txt

@@ -406,3 +406,8 @@ endif()
 target_compile_features(agent_lib PUBLIC ${CXX_COMPILE_FEATURES})
 target_clangformat_setup(agent_lib)
 target_clangtidy_setup(agent_lib)
+
+include(../cmake/document.cmake)
+if (DOXYGEN_FOUND)
+  doxygen_add_docs(docs ../README.md ${AGENT_SOURCES})
+endif()

appveyor.yml

@@ -50,7 +50,7 @@ before_build:
       pip install conan
       conan export conan/mqtt_cpp
       conan export conan/mruby
-      conan install . -if build --build=missing -pr %CONAN_PROFILE% -o run_tests=False -o shared=%SHARED%
+      conan install . -if build --build=missing -pr %CONAN_PROFILE% -o run_tests=False -o shared=%SHARED% -o with_docs=False
   - sh: |-
       export PATH=$HOME/venv3.10/bin:$PATH
       if [[ $APPVEYOR_BUILD_WORKER_IMAGE = "Ubuntu2004" ]]
@@ -68,7 +68,7 @@ before_build:
       pip install conan
       conan export conan/mqtt_cpp
       conan export conan/mruby
-      conan install . -if build --build=missing -pr $CONAN_PROFILE -o run_tests=False -o shared=$SHARED
+      conan install . -if build --build=missing -pr $CONAN_PROFILE -o run_tests=False -o shared=$SHARED -o with_docs=False
 
 build:
   verbosity: minimal

cmake/document.cmake

@@ -0,0 +1,20 @@
+find_package(Doxygen OPTIONAL_COMPONENTS dot)
+if (DOXYGEN_FOUND)
+  set(DOXYGEN_PROJECT_NAME "MTConnect C++ Agent")
+  set(DOXYGEN_PROJECT_BRIEF "MTConnect Reference C++ Agent")
+  set(DOXYGEN_PROJECT_LOGO "${PROJECT_SOURCE_DIR}/styles/favicon.ico")
+  set(DOXYGEN_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}/Documentation")
+  set(DOXYGEN_USE_MDFILE_AS_MAINPAGE "${PROJECT_SOURCE_DIR}/README.md")
+  set(DOXYGEN_GENERATE_LATEX NO)
+  set(DOXYGEN_DOCSET_BUNDLE_ID org.mtconnect.agent)
+  set(DOXYGEN_DOCSET_PUBLISHER_ID org.amtonline)
+  set(DOXYGEN_DOCSET_PUBLISHER_NAME "Association for Manufacturing Technology")
+  set(DOXYGEN_TAB_SIZE 2)
+  set(DOXYGEN_BUILTIN_STL_SUPPORT YES)
+  set(DOXYGEN_UML_LOOK NO)
+  set(DOXYGEN_DOT_IMAGE_FORMAT svg)
+  set(DOXYGEN_INTERACTIVE_SVG YES)
+  set(DOXYGEN_INCLUDE_PATH "${CONAN_INCLUDE_DIRS}")
+  set(DOXYGEN_HTML_COLORSTYLE "AUTO_DARK")
+  set(DOXYGEN_MAX_DOT_GRAPH_DEPTH 3)
+endif()

conanfile.py

@@ -5,6 +5,7 @@
 import re
 import itertools as it
 import glob
+import subprocess
 from conan.tools.microsoft import is_msvc, is_msvc_static_runtime
 
 class MTConnectAgentConan(ConanFile):
@@ -16,7 +17,8 @@ class MTConnectAgentConan(ConanFile):
     settings = "os", "compiler", "arch", "build_type", "arch_build"
     options = { "run_tests": [True, False], "build_tests": [True, False], 
                 "without_ipv6": [True, False], "with_ruby": [True, False],
-                 "development" : [True, False], "shared": [True, False], "winver": "ANY" }
+                 "development" : [True, False], "shared": [True, False], "winver": "ANY",
+                 "with_docs" : [True, False] }
     description = "MTConnect reference C++ agent copyright Association for Manufacturing Technology"
 
     requires = ["boost/1.79.0@#3249d9bd2b863a9489767bf9c8a05b4b",
@@ -25,7 +27,7 @@ class MTConnectAgentConan(ConanFile):
                 "nlohmann_json/3.9.1@#a41bc0deaf7f40e7b97e548359ccf14d", 
                 "openssl/3.0.5@#40f4488f02b36c1193b68f585131e8ef",
                 "mqtt_cpp/13.1.0"]
-    
+
     build_policy = "missing"
     default_options = {
         "run_tests": True,
@@ -35,6 +37,7 @@ class MTConnectAgentConan(ConanFile):
         "development": False,
         "shared": False,
         "winver": "0x600",
+        "with_docs": True,
 
         "boost:shared": False,
         "boost:without_python": True,
@@ -109,6 +112,12 @@ def configure(self):
             self.options["gtest"].shared = True
             self.options["openssl"].shared = True
 
+    def build_requirements(self):
+        if self.options.with_docs:
+            res = subprocess.run(["doxygen --version"], shell=True, text=True, capture_output=True)
+            if (res.returncode != 0 or not res.stdout.startswith('1.9')):
+                self.tool_requires("doxygen/1.9.4@#19fe2ac34109f3119190869a4d0ffbcb")
+
     def requirements(self):
         if not self.windows_xp:
             self.requires("gtest/1.10.0")

src/mtconnect/agent.cpp

@@ -182,13 +182,13 @@ namespace mtconnect {
   void Agent::start()
   {
     NAMED_SCOPE("Agent::start");
-    
+
     if (m_started)
     {
       LOG(warning) << "Agent already started.";
       return;
     }
-    
+
     try
     {
       m_beforeStartHooks.exec(*this);
@@ -213,20 +213,20 @@ namespace mtconnect {
       LOG(fatal) << "Cannot start server: " << e.what();
       std::exit(1);
     }
-    
+
     m_started = true;
   }
 
   void Agent::stop()
   {
     NAMED_SCOPE("Agent::stop");
-    
+
     if (!m_started)
     {
       LOG(warning) << "Agent already stopped.";
       return;
     }
-    
+
     m_beforeStopHooks.exec(*this);
 
     // Stop all adapter threads...
@@ -248,7 +248,7 @@ namespace mtconnect {
     }
 
     LOG(info) << "Shutting down completed";
-    
+
     m_started = false;
   }
 
@@ -272,7 +272,7 @@ namespace mtconnect {
     if (uuid)
       device = findDeviceByUUIDorName(*uuid);
     else
-      device = defaultDevice();
+      device = getDefaultDevice();
 
     if (device && device->getAssetChanged() && device->getAssetRemoved())
     {
@@ -898,7 +898,7 @@ namespace mtconnect {
   DevicePtr Agent::getDeviceByName(const std::string &name) const
   {
     if (name.empty())
-      return defaultDevice();
+      return getDefaultDevice();
 
     auto &idx = m_deviceIndex.get<ByName>();
     auto devPos = idx.find(name);
@@ -911,7 +911,7 @@ namespace mtconnect {
   DevicePtr Agent::getDeviceByName(const std::string &name)
   {
     if (name.empty())
-      return defaultDevice();
+      return getDefaultDevice();
 
     auto &idx = m_deviceIndex.get<ByName>();
     auto devPos = idx.find(name);
@@ -924,7 +924,7 @@ namespace mtconnect {
   DevicePtr Agent::findDeviceByUUIDorName(const std::string &idOrName) const
   {
     if (idOrName.empty())
-      return defaultDevice();
+      return getDefaultDevice();
 
     DevicePtr res;
     if (auto d = m_deviceIndex.get<ByUuid>().find(idOrName); d != m_deviceIndex.get<ByUuid>().end())