Add documentation comments and nodiscard attributes

mogemimi · Aug 23, 2019 · 6547456 · 6547456
1 parent 3ba1ddf
commit 6547456
Show file tree

Hide file tree

Showing 4 changed files with 22 additions and 5 deletions.
diff --git a/include/Pomdog/Content/AssetBuilders/ShaderBuilder.hpp b/include/Pomdog/Content/AssetBuilders/ShaderBuilder.hpp
@@ -31,35 +31,44 @@ class POMDOG_EXPORT Builder<Shader> final {
 
     ~Builder();
 
+    /// Sets the string of the GLSL source code, and the entry point of the function.
     Builder& SetGLSL(const void* shaderSource, std::size_t byteLength);
 
+    /// Sets the file path to GLSL file, and the entry point of the function.
     Builder& SetGLSLFromFile(const std::string& filePath);
 
+    /// Sets the string of the HLSL source code, and the entry point of the function.
     Builder& SetHLSL(
         const void* shaderSource,
         std::size_t byteLength,
         const std::string& entryPoint);
 
+    /// Sets the data from a precompiled HLSL binary, and the entry point of the function.
     Builder& SetHLSLPrecompiled(
         const void* shaderSource,
         std::size_t byteLength);
 
+    /// Sets the file path to HLSL file, and the entry point of the function.
     Builder& SetHLSLFromFile(
         const std::string& filePath,
         const std::string& entryPoint);
 
+    /// Sets the string of the Metal source code, and the entry point of the function.
     Builder& SetMetal(
         const void* shaderSource,
         std::size_t byteLength,
         const std::string& entryPoint);
 
+    /// Sets the file path to `.metal` file, and the entry point of the function.
     Builder& SetMetalFromFile(
         const std::string& filePath,
         const std::string& entryPoint);
 
+    /// Sets the entry point of the function in the default library.
     Builder& SetMetalFromLibrary(const std::string& entryPoint);
 
-    std::shared_ptr<Shader> Build();
+    /// Returns an object representing shader function.
+    [[nodiscard]] std::shared_ptr<Shader> Build();
 
 private:
     class Impl;

diff --git a/include/Pomdog/Graphics/ShaderCompilers/GLSLCompiler.hpp b/include/Pomdog/Graphics/ShaderCompilers/GLSLCompiler.hpp
@@ -17,7 +17,9 @@ class Shader;
 namespace Pomdog::ShaderCompilers {
 
 struct POMDOG_EXPORT GLSLCompiler final {
-    static std::unique_ptr<Shader> CreateShader(
+    /// Creates a shader from a string of source code.
+    [[nodiscard]] static std::unique_ptr<Shader>
+    CreateShader(
         GraphicsDevice& graphicsDevice,
         const void* shaderSource,
         std::size_t byteLength,

diff --git a/include/Pomdog/Graphics/ShaderCompilers/HLSLCompiler.hpp b/include/Pomdog/Graphics/ShaderCompilers/HLSLCompiler.hpp
@@ -17,13 +17,17 @@ class Shader;
 namespace Pomdog::ShaderCompilers {
 
 struct POMDOG_EXPORT HLSLCompiler final {
-    static std::unique_ptr<Shader> CreateShaderFromBinary(
+    /// Creates a shader from a string of source code.
+    [[nodiscard]] static std::unique_ptr<Shader>
+    CreateShaderFromBinary(
         GraphicsDevice& graphicsDevice,
         const void* shaderSource,
         std::size_t byteLength,
         ShaderPipelineStage pipelineStage);
 
-    static std::unique_ptr<Shader> CreateShaderFromSource(
+    /// Creates a shader from precompiled shader binary data.
+    [[nodiscard]] static std::unique_ptr<Shader>
+    CreateShaderFromSource(
         GraphicsDevice& graphicsDevice,
         const void* shaderSource,
         std::size_t byteLength,

diff --git a/include/Pomdog/Graphics/ShaderCompilers/MetalCompiler.hpp b/include/Pomdog/Graphics/ShaderCompilers/MetalCompiler.hpp
@@ -16,7 +16,9 @@ class Shader;
 namespace Pomdog::ShaderCompilers {
 
 struct POMDOG_EXPORT MetalCompiler final {
-    static std::unique_ptr<Shader> CreateShaderFromSource(
+    /// Creates a shader from a string of source code.
+    [[nodiscard]] static std::unique_ptr<Shader>
+    CreateShaderFromSource(
         GraphicsDevice& graphicsDevice,
         const void* shaderSource,
         std::size_t byteLength,