From 89582ef54d142333e76fef94aee242a1f3cda181 Mon Sep 17 00:00:00 2001
From: Vladislav Oleshko <vladislav.oleshko@gmail.com>
Date: Wed, 27 Jul 2022 10:06:08 +0300
Subject: [PATCH] Update doc comments

---
 src/Magnum/GL/AbstractShaderProgram.h | 28 ++++++++++++++++-----------
 src/Magnum/GL/Shader.h                | 19 ++++++++++--------
 2 files changed, 28 insertions(+), 19 deletions(-)

diff --git a/src/Magnum/GL/AbstractShaderProgram.h b/src/Magnum/GL/AbstractShaderProgram.h
index 60d2f1386..48d1b2b17 100644
--- a/src/Magnum/GL/AbstractShaderProgram.h
+++ b/src/Magnum/GL/AbstractShaderProgram.h
@@ -1265,18 +1265,13 @@ class MAGNUM_GL_EXPORT AbstractShaderProgram: public AbstractObject {
         bool isLinkFinished();
 
     protected:
-        /**
-         * @brief Link the shaders
+        /** @brief Link the shaders
          *
+         * Calls @ref submitLink() on all shaders first, then @ref checkLink().
          * Returns @cpp false @ce if linking of any shader failed, @cpp true @ce
-         * if everything succeeded. Linker message (if any) is printed to error
-         * output. All attached shaders must be compiled with
-         * @ref Shader::compile() before linking. The operation is batched in a
+         * if everything succeeded. The operation is batched in a
          * way that allows the driver to link multiple shaders simultaneously
          * (i.e. in multiple threads).
-         * @see @fn_gl_keyword{LinkProgram}, @fn_gl_keyword{GetProgram} with
-         *      @def_gl{LINK_STATUS} and @def_gl{INFO_LOG_LENGTH},
-         *      @fn_gl_keyword{GetProgramInfoLog}
          */
         static bool link(std::initializer_list<Containers::Reference<AbstractShaderProgram>> shaders);
 
@@ -1452,22 +1447,33 @@ class MAGNUM_GL_EXPORT AbstractShaderProgram: public AbstractObject {
         /**
          * @brief Link the shader
          *
-         * Links single shader. If possible, prefer to link multiple shaders
-         * at once using @ref link(std::initializer_list<Containers::Reference<AbstractShaderProgram>>)
+         * Calls @ref submitLink(), then @ref checkLink().
+         * If possible, prefer to link multiple shaders at once using
+         * @ref link(std::initializer_list<Containers::Reference<AbstractShaderProgram>>)
          * for improved performance, see its documentation for more
          * information.
          */
         bool link();
 
         /**
-         * @brief Submit single shader for linking
+         * @brief Submit for linking
+         *
+         * The attached shaders must be compiled with @ref Shader::compile() before linking.
          *
+         * @see @fn_gl_keyword{LinkProgram}
          */
         void submitLink();
 
         /**
          * @brief Check link status and await completion
          *
+         * Returns @cpp false @ce if linking failed, @cpp true @ce on success.
+         * Linker message (if any) is printed to error output. This function
+         * must be called only after @ref submitLink().
+         *
+         * @see @fn_gl_keyword{GetProgram} with
+         *      @def_gl{LINK_STATUS} and @def_gl{INFO_LOG_LENGTH},
+         *      @fn_gl_keyword{GetProgramInfoLog}
          */
         bool checkLink();
 
diff --git a/src/Magnum/GL/Shader.h b/src/Magnum/GL/Shader.h
index 9d61d2a40..af7065c76 100644
--- a/src/Magnum/GL/Shader.h
+++ b/src/Magnum/GL/Shader.h
@@ -510,14 +510,11 @@ class MAGNUM_GL_EXPORT Shader: public AbstractObject {
         /**
          * @brief Compile multiple shaders simultaneously
          *
+         * Calls @ref submitCompile() on all shaders first, then @ref checkCompile().
          * Returns @cpp false @ce if compilation of any shader failed,
-         * @cpp true @ce if everything succeeded. Compiler messages (if any)
-         * are printed to error output. The operation is batched in a way that
+         * @cpp true @ce if everything succeeded. The operation is batched in a way that
          * allows the driver to perform multiple compilations simultaneously
          * (i.e. in multiple threads).
-         * @see @fn_gl_keyword{ShaderSource}, @fn_gl_keyword{CompileShader},
-         *      @fn_gl_keyword{GetShader} with @def_gl{COMPILE_STATUS} and
-         *      @def_gl{INFO_LOG_LENGTH}, @fn_gl_keyword{GetShaderInfoLog}
          */
         static bool compile(std::initializer_list<Containers::Reference<Shader>> shaders);
 
@@ -636,8 +633,9 @@ class MAGNUM_GL_EXPORT Shader: public AbstractObject {
         /**
          * @brief Compile shader
          *
-         * Compiles single shader. Prefer to compile multiple shaders at once
-         * using @ref compile(std::initializer_list<Containers::Reference<Shader>>)
+         * Calls @ref submitCompile(), then @ref checkCompile().
+         * Prefer to compile multiple shaders at once using
+         * @ref compile(std::initializer_list<Containers::Reference<Shader>>)
          * for improved performance, see its documentation for more
          * information.
          */
@@ -646,13 +644,18 @@ class MAGNUM_GL_EXPORT Shader: public AbstractObject {
         /**
          * @brief Submit shader for compilation
          *
-         * Submits shader for compilation.
+         * @see @fn_gl_keyword{ShaderSource}, @fn_gl_keyword{CompileShader}
          */
         void submitCompile();
 
         /**
          * @brief Check compilation status and await completion
          *
+         * Returns @cpp false @ce if compilation of failed, @cpp true @ce on success.
+         * This function must be called only after @ref submitCompile().
+         *
+         * @see @fn_gl_keyword{GetShader} with @def_gl{COMPILE_STATUS} and
+         *      @def_gl{INFO_LOG_LENGTH}, @fn_gl_keyword{GetShaderInfoLog}
          */
         bool checkCompile();