Merge pull request #186 from Esri/tdunn/20171122-doc-build

Update toolkit API doc

Author: lsmallwood

Import/Esri/ArcGISRuntime/Toolkit/Controls/CppApi/CoordinateConversion.qml

@@ -6,6 +6,7 @@ import Esri.ArcGISRuntime.Toolkit.CppApi 100.2
 
 /*!
     \qmltype CoordinateConversion
+    \inqmlmodule Esri.ArcGISRuntime.Toolkit.Controls
     \ingroup ToolCoordinateConversion
     \since Esri.ArcGISRutime 100.2
     \brief The user interface for the coordinate conversion tool.

Plugin/CppApi/include/ArcGISCompassController.h

@@ -45,7 +45,9 @@ class TOOLKIT_EXPORT ArcGISCompassController : public AbstractTool
   ~ArcGISCompassController();
 
   bool setView(Esri::ArcGISRuntime::GeoView* geoView);
+  /*! \internal */
   bool setView(Esri::ArcGISRuntime::MapQuickView* mapView);
+  /*! \internal */
   bool setView(Esri::ArcGISRuntime::SceneQuickView* sceneView);
 
   double heading() const;

Plugin/CppApi/include/CoordinateConversionController.h

@@ -52,6 +52,7 @@ class TOOLKIT_EXPORT CoordinateConversionController : public AbstractTool
   Q_PROPERTY(CoordinateConversionOptions::UtmConversionMode inputUtmConversionMode READ inputUtmConversionMode WRITE setInputUtmConversionMode NOTIFY inputUtmConversionModeChanged)
 
   // internal: support for nested default property "options" objects
+  /*! \internal */
   Q_PRIVATE_PROPERTY(CoordinateConversionController::self(), QQmlListProperty<QObject> objects READ objects DESIGNABLE false)
   Q_CLASSINFO("DefaultProperty", "objects")
 

Plugin/CppApi/source/AbstractTool.cpp

@@ -18,39 +18,105 @@ namespace ArcGISRuntime
 {
 namespace Toolkit
 {
+/*!
+  \class Esri::ArcGISRuntime::Toolkit::AbstractTool
+  \inmodule ArcGISQtToolkit
+  \brief Base class for classes that implement individual tools.
+  \since Esri::ArcGISRuntime 100.2
 
+  AbstractTool provides functions and properties that all derived tools share.
+
+  \note You cannot create an object of this class. Instead, create a tool
+  object from a derived class.
+ */
+
+/*!
+   \brief The constructor that accepts an optional \a parent object.
+ */
 AbstractTool::AbstractTool(QObject* parent /*= nullptr*/):
   QObject(parent)
 {
 
 }
 
+/*!
+   \brief The destructor.
+ */
 AbstractTool::~AbstractTool()
 {
 
 }
 
+/*!
+  \brief Reimplement this method in subclasses to handle a click at
+  geographic coordinate \a pos.
+
+  Returns \c false.
+ */
 bool AbstractTool::handleClick(const Point& pos)
 {
   Q_UNUSED(pos)
   return false;
 }
 
+/*!
+  \brief Reimplement this method in subclasses to set tool properties.
+  \list
+  \li \a properties - A QVariantMap containing property settings.
+  \endlist
+
+  A tool property is defined as a key-value pair where the key is a QString
+  and the value is a QVariant. Properties are useful for general settings
+  which you wish to persist for the tool, such as default modes.
+ */
 void AbstractTool::setProperties(const QVariantMap&)
 {
 
 }
 
+/*!
+   \brief Sets whether this tool is active to \a active.
+ */
 void AbstractTool::setActive(bool active)
 {
   m_active = active;
 }
 
+/*!
+   \brief Returns whether this tool is active (\c true) or not (\c false).
+ */
 bool AbstractTool::isActive() const
 {
   return m_active;
 }
 
+// Signals
+/*!
+  \fn void Esri::ArcGISRuntime::Toolkit::AbstractTool::errorOccurred(const Error& error)
+  \brief Signal emitted when this tool encounters an error.
+
+  \list
+    \li \a error - Details about the error that occurred.
+  \endlist
+ */
+
+/*!
+  \fn void Esri::ArcGISRuntime::Toolkit::AbstractTool::propertyChanged(const QString& propertyName, const QVariant& propertyValue)
+  \brief Signal emitted when a property of this tool changes.
+
+  \list
+    \li \a propertyName - The changed property's name.
+    \li \a propertyValue - The changed property's new value.
+  \endlist
+ */
+
+// Properties
+
+/*!
+  \fn QString AbstractTool::toolName() const
+  \brief Returns the name of this tool.
+ */
+
 } // Toolkit
 } // ArcGISRuntime
 } // Esri

Plugin/CppApi/source/ArcGISCompassController.cpp

@@ -29,12 +29,15 @@ namespace Toolkit
 
 /*!
   \class Esri::ArcGISRuntime::Toolkit::ArcGISCompassController
-  \ingroup ToolArcGISCompass
   \inmodule ArcGISQtToolkit
-  \since Esri::ArcGISRuntime 100.2
+  \ingroup ToolArcGISCompass
   \brief The controller for the ArcGIS Compass tool.
+  \since Esri::ArcGISRuntime 100.2
  */
 
+/*!
+   \brief The constructor that accepts an optional \a parent object.
+ */
 ArcGISCompassController::ArcGISCompassController(QObject *parent):
   AbstractTool(parent)
 {
@@ -48,10 +51,17 @@ ArcGISCompassController::ArcGISCompassController(QObject *parent):
   });
 }
 
+/*!
+   \brief The destructor.
+ */
 ArcGISCompassController::~ArcGISCompassController()
 {
 }
 
+/*!
+   \property ArcGISCompassController::heading
+   \brief The compass heading in degrees.
+ */
 void ArcGISCompassController::setHeading(double rotation)
 {
   if (m_heading == rotation)
@@ -68,6 +78,10 @@ void ArcGISCompassController::setHeading(double rotation)
   }
 }
 
+/*!
+   \property ArcGISCompassController::autoHide
+   \brief Whether the compass should be hidden when its heading is north (zero degrees).
+ */
 void ArcGISCompassController::setAutoHide(bool autoHide)
 {
   if (m_autoHide == autoHide)
@@ -77,6 +91,12 @@ void ArcGISCompassController::setAutoHide(bool autoHide)
   emit autoHideChanged();
 }
 
+/*!
+  \fn Esri::ArcGISRuntime::Toolkit::ArcGISCompassController::setView(Esri::ArcGISRuntime::GeoView* geoView)
+  \brief Sets the \c Esri::ArcGISRuntime::GeoView associated with the compass to \a geoView.
+
+  Returns \c true on success.
+ */
 bool ArcGISCompassController::setView(GeoView *geoView)
 {
   if (!geoView)

Plugin/CppApi/source/ArcGISRuntimeToolkit.cpp

@@ -24,6 +24,16 @@ namespace ArcGISRuntime
 {
 namespace Toolkit
 {
+/*!
+  \class Esri::ArcGISRuntime::Toolkit::ArcGISRuntimeToolkit
+  \inmodule ArcGISQtToolkit
+  \since Esri::ArcGISRuntime 100.2
+  \brief The main plugin class for the ArcGISRuntimeToolkit.
+
+  You must call the static \l registerToolkitTypes function
+  to ensure all the types are accessible in the QML environment.
+  You may alternately do this manually if you only need specific types.
+ */
 
 static CoordinateConversionOptions* m_optionsProvider = nullptr;
 
@@ -37,6 +47,9 @@ QObject* optionsProvider(QQmlEngine* engine, QJSEngine*)
   return m_optionsProvider;
 }
 
+/*!
+   \brief Constructor that accepts an optional \a parent object.
+ */
 ArcGISRuntimeToolkit::ArcGISRuntimeToolkit(QObject* parent) :
   QQmlExtensionPlugin(parent)
 {
@@ -45,11 +58,36 @@ ArcGISRuntimeToolkit::ArcGISRuntimeToolkit(QObject* parent) :
 #endif
 }
 
+/*!
+  \brief Type registration function to ensure the types are accessible
+  in the QML environment.
+
+  You can use this method if you want to customize the import path. For ease
+  of use, \l registerToolkitTypes can be used instead without needing to instantiate
+  this class.
+
+  \list
+  \li \a uri - The namespace in which to register the types.
+  \endlist
+ */
 void ArcGISRuntimeToolkit::registerTypes(const char* uri)
 {
   registerToolkitTypes(uri);
 }
 
+/*!
+  \brief Static type registration function to ensure the types are accessible
+  in the QML environment.
+
+  This is the starting point for most uses of the ArcGISRuntimeToolkit. If you
+  want to use the ArcGISRuntimeToolkit out of the box, then this method (with
+  the default argument) will register all the types with the default import
+  path.
+
+  \list
+  \li \a uri - The namespace in which to register the types.
+  \endlist
+ */
 void ArcGISRuntimeToolkit::registerToolkitTypes(const char* uri)
 {
   // singletons