Flush out some class/method documentation. (#476)

This CL adds class/method documentation to a few more classes.

6 files changed, 32 insertions, 68 deletions

diff --git a/samples/config_helper.h b/samples/config_helper.h
index 06c0c27..cc351d6 100644
--- a/samples/config_helper.h
+++ b/samples/config_helper.h
@@ -23,15 +23,15 @@
 
 namespace sample {
 
-// Proof of concept implementation showing how to provide and use
-// EngineConfig within sample amber program.
+/// Proof of concept implementation showing how to provide and use
+/// EngineConfig within sample amber program.
 class ConfigHelperImpl {
  public:
   virtual ~ConfigHelperImpl();
 
-  // Create instance and device and return them as amber::EngineConfig.
-  // |required_features| and |required_extensions| contain lists of
-  // required features and required extensions, respectively.
+  /// Create instance and device and return them as amber::EngineConfig.
+  /// |required_features| and |required_extensions| contain lists of
+  /// required features and required extensions, respectively.
   virtual amber::Result CreateConfig(
       uint32_t engine_major,
       uint32_t engine_minor,
@@ -43,17 +43,17 @@ class ConfigHelperImpl {
       std::unique_ptr<amber::EngineConfig>* config) = 0;
 };
 
-// Wrapper of ConfigHelperImpl.
+/// Wrapper of ConfigHelperImpl.
 class ConfigHelper {
  public:
   ConfigHelper();
   ~ConfigHelper();
 
-  // Create instance and device and return them as amber::EngineConfig.
-  // |required_features| and |required_extensions| contain lists of
-  // required features and required extensions, respectively. |engine|
-  // indicates whether the caller required VulkanEngineConfig or
-  // DawnEngineConfig.
+  /// Create instance and device and return them as amber::EngineConfig.
+  /// |required_features| and |required_extensions| contain lists of
+  /// required features and required extensions, respectively. |engine|
+  /// indicates whether the caller required VulkanEngineConfig or
+  /// DawnEngineConfig.
   amber::Result CreateConfig(
       amber::EngineType engine,
       uint32_t engine_major,
diff --git a/samples/config_helper_dawn.cc b/samples/config_helper_dawn.cc
index e733b88..c633f97 100644
--- a/samples/config_helper_dawn.cc
+++ b/samples/config_helper_dawn.cc
@@ -16,7 +16,6 @@
 
 #include <iostream>
 
-#include "samples/dawn_device_metal.h"
 namespace sample {
 
 ConfigHelperDawn::ConfigHelperDawn() = default;
diff --git a/samples/config_helper_dawn.h b/samples/config_helper_dawn.h
index 7b8b598..1f0fdff 100644
--- a/samples/config_helper_dawn.h
+++ b/samples/config_helper_dawn.h
@@ -24,19 +24,18 @@
 #include "amber/amber_dawn.h"
 #include "dawn_native/DawnNative.h"
 #include "samples/config_helper.h"
-#include "samples/dawn_device_metal.h"
 
 namespace sample {
 
-// Child class of ConfigHelperImpl for Dawn.
+/// Child class of ConfigHelperImpl for Dawn.
 class ConfigHelperDawn : public ConfigHelperImpl {
  public:
   ConfigHelperDawn();
   ~ConfigHelperDawn() override;
 
-  // Create a Dawn instance and device and return them as
-  // amber::DawnEngineConfig.  Engine version number and features
-  // and extension lists are ignored.
+  /// Create a Dawn instance and device and return them as
+  /// amber::DawnEngineConfig.  Engine version number and features
+  /// and extension lists are ignored.
   amber::Result CreateConfig(
       uint32_t engine_major,
       uint32_t engine_minor,
diff --git a/samples/config_helper_vulkan.h b/samples/config_helper_vulkan.h
index b195972..d0d312d 100644
--- a/samples/config_helper_vulkan.h
+++ b/samples/config_helper_vulkan.h
@@ -31,16 +31,16 @@
 
 namespace sample {
 
-// Child class of ConfigHelperImpl for Vulkan.
+/// Child class of ConfigHelperImpl for Vulkan.
 class ConfigHelperVulkan : public ConfigHelperImpl {
  public:
   ConfigHelperVulkan();
   ~ConfigHelperVulkan() override;
 
-  // Create Vulkan instance and device and return them as
-  // amber::VulkanEngineConfig. Required Vulkan device features and
-  // extensions are given in |required_features| and
-  // |required_extensions|, respectively.
+  /// Create Vulkan instance and device and return them as
+  /// amber::VulkanEngineConfig. Required Vulkan device features and
+  /// extensions are given in |required_features| and
+  /// |required_extensions|, respectively.
   amber::Result CreateConfig(
       uint32_t engine_major,
       uint32_t engine_minor,
@@ -52,42 +52,42 @@ class ConfigHelperVulkan : public ConfigHelperImpl {
       std::unique_ptr<amber::EngineConfig>* config) override;
 
  private:
-  // Create Vulkan instance.
+  /// Create Vulkan instance.
   amber::Result CreateVulkanInstance(
       uint32_t engine_major,
       uint32_t engine_minor,
       std::vector<std::string> required_instance_extensions,
       bool disable_validation_layer);
 
-  // Create |vulkan_callback_| that reports validation layer errors
-  // via debugCallback() function in config_helper_vulkan.cc.
+  /// Create |vulkan_callback_| that reports validation layer errors
+  /// via debugCallback() function in config_helper_vulkan.cc.
   amber::Result CreateDebugReportCallback();
 
-  // Choose Vulkan physical device that supports both
-  // |required_features| and |required_extensions|.
+  /// Choose Vulkan physical device that supports both
+  /// |required_features| and |required_extensions|.
   amber::Result ChooseVulkanPhysicalDevice(
       const std::vector<std::string>& required_features,
       const std::vector<std::string>& required_extensions);
 
-  // Create Vulkan logical device that enables both
-  // |required_features| and |required_extensions|.
+  /// Create Vulkan logical device that enables both
+  /// |required_features| and |required_extensions|.
   amber::Result CreateVulkanDevice(
       const std::vector<std::string>& required_features,
       const std::vector<std::string>& required_extensions);
 
-  // Sets up the device creation to use VkPhysicalDeviceFeatures.
+  /// Sets up the device creation to use VkPhysicalDeviceFeatures.
   amber::Result CreateDeviceWithFeatures1(
       const std::vector<std::string>& required_features,
       VkDeviceCreateInfo* info);
-  // Sets up the device creation to use VkPhysicalDeviceFeatures2KHR.
+  /// Sets up the device creation to use VkPhysicalDeviceFeatures2KHR.
   amber::Result CreateDeviceWithFeatures2(
       const std::vector<std::string>& required_features,
       VkDeviceCreateInfo* info);
 
-  // Creates the physical device given the device |info|.
+  /// Creates the physical device given the device |info|.
   amber::Result DoCreateDevice(VkDeviceCreateInfo* info);
 
-  // Writes information related to the vulkan instance to stdout.
+  /// Writes information related to the vulkan instance to stdout.
   void DumpPhysicalDeviceInfo();
 
   VkInstance vulkan_instance_ = VK_NULL_HANDLE;
diff --git a/samples/dawn_device_metal.h b/samples/dawn_device_metal.h
deleted file mode 100644
index ccdd186..0000000
--- a/samples/dawn_device_metal.h
+++ /dev/null
@@ -1,34 +0,0 @@
-// Copyright 2018 The Amber Authors.
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-#ifndef SAMPLES_DAWN_DEVICE_METAL_H_
-#define SAMPLES_DAWN_DEVICE_METAL_H_
-
-#if AMBER_DAWN_METAL
-
-#include "amber/result.h"
-#include "dawn/dawncpp.h"
-#include "dawn_native/DawnNative.h"
-
-namespace sample {
-namespace dawn {
-
-amber::Result CreateMetalDevice(::dawn_native::Instance*, ::dawn::Device*);
-
-}  // namespace dawn
-}  // namespace sample
-
-#endif  // AMBER_DAWN_METAL
-
-#endif  // SAMPLES_DAWN_DEVICE_METAL_H_
diff --git a/samples/log.h b/samples/log.h
index ff9b316..5b5f53b 100644
--- a/samples/log.h
+++ b/samples/log.h
@@ -19,7 +19,7 @@
 
 namespace sample {
 
-// This method is used for debug reports from Vulkan validation layers.
+/// This method is used for debug reports from Vulkan validation layers.
 void LogError(const std::string& msg);
 
 }  // namespace sample