doc: cleaned up cross-links and annotations for examples

doc/mainpage.md

@@ -66,13 +66,15 @@ Data manipulation:
 
 # Examples
 
-| Scenario           | Platform | C++ API                          | C API                          |
-| :----              | :---     | :----                            | :---                           |
-| Introduction       | CPU      | @ref cpu_getting_started_cpp     |                                |
-|                    | GPU      | @ref gpu_getting_started_cpp     | @ref gpu_getting_started_c     |
-| fp32 inference     | CPU      | @ref cpu_cnn_inference_fp32_cpp  | @ref cpu_cnn_inference_fp32_c  |
-|                    |          | @ref cpu_rnn_inference_fp32_cpp  |                                |
-| int8 inference     | CPU      | @ref cpu_cnn_inference_int8_cpp  |                                |
-|                    |          | @ref cpu_rnn_inference_int8_cpp  |                                |
-| training           | CPU      | @ref cpu_cnn_training_fp32_cpp   | @ref cpu_cnn_training_fp32_c   |
-|                    | CPU      | @ref cpu_rnn_training_fp32_cpp   |                                |
+| Topic              | Engine   | C++ API                                | C API                          |
+| :----              | :---     | :----                                  | :---                           |
+| Tutorials          | CPU      | @ref cpu_getting_started_cpp           |                                |
+|                    |          | @ref cpu_memory_format_propagation_cpp |                                |
+|                    |          | @ref cpu_performance_profiling_cpp     |                                |
+|                    | GPU      | @ref gpu_getting_started_cpp           | @ref gpu_getting_started_c     |
+| fp32 inference     | CPU      | @ref cpu_cnn_inference_fp32_cpp        | @ref cpu_cnn_inference_fp32_c  |
+|                    |          | @ref cpu_rnn_inference_fp32_cpp        |                                |
+| int8 inference     | CPU      | @ref cpu_cnn_inference_int8_cpp        |                                |
+|                    |          | @ref cpu_rnn_inference_int8_cpp        |                                |
+| training           | CPU      | @ref cpu_cnn_training_fp32_cpp         | @ref cpu_cnn_training_fp32_c   |
+|                    | CPU      | @ref cpu_rnn_training_fp32_cpp         |                                |

examples/cpu_cnn_inference_fp32.c

@@ -15,13 +15,16 @@
 *******************************************************************************/
 
 /// @example cpu_cnn_inference_fp32.c
-/// @copydoc cpu_cnn_inference_fp32_c
-///
+/// @copybrief cpu_cnn_inference_fp32_c
+/// > Annotated version: @ref cpu_cnn_inference_fp32_c
+
 /// @page cpu_cnn_inference_fp32_c CNN fp32 inference example
-///
 /// This C API example demonstrates how to build an AlexNet neural
-/// network topology for forward-pass inference. Some key take-aways
-/// include:
+/// network topology for forward-pass inference. 
+///
+/// > Example code: @ref cpu_cnn_inference_fp32.c
+///
+/// Some key take-aways include:
 ///
 /// * How tensors are implemented and submitted to primitives.
 /// * How primitives are created.

examples/cpu_cnn_inference_fp32.cpp

@@ -15,14 +15,16 @@
 *******************************************************************************/
 
 /// @example cpu_cnn_inference_fp32.cpp
-/// Annotated version: @ref cpu_cnn_inference_fp32_cpp
-///
+/// @copybrief cpu_cnn_inference_fp32_cpp
+/// > Annotated version: @ref cpu_cnn_inference_fp32_cpp
+
 /// @page cpu_cnn_inference_fp32_cpp CNN fp32 inference example
-/// Full example text: @ref cpu_cnn_inference_fp32.cpp
-///
 /// This C++ API example demonstrates how to build an AlexNet neural
-/// network topology for forward-pass inference. Some key take-aways
-/// include:
+/// network topology for forward-pass inference. 
+///
+/// > Example code: @ref cpu_cnn_inference_fp32.cpp
+///
+/// Some key take-aways include:
 ///
 /// * How tensors are implemented and submitted to primitives.
 /// * How primitives are created.

examples/cpu_cnn_inference_int8.cpp

@@ -15,13 +15,14 @@
 *******************************************************************************/
 
 /// @example cpu_cnn_inference_int8.cpp
-/// Annotated version: @ref cpu_cnn_inference_int8_cpp
-///
+/// @copybrief cpu_cnn_inference_int8_cpp
+/// > Annotated version: @ref cpu_cnn_inference_int8_cpp
+
 /// @page cpu_cnn_inference_int8_cpp CNN int8 inference example
-/// Full example text: @ref cpu_cnn_inference_int8.cpp
-///
 /// This C++ API example demonstrates how to run AlexNet's conv3 and relu3
 /// with int8 data type.
+///
+/// > Example code: @ref cpu_cnn_inference_int8.cpp
 
 #include "mkldnn.hpp"
 #include <iostream>

examples/cpu_cnn_training_fp32.c

@@ -15,14 +15,11 @@
 *******************************************************************************/
 
 /// @example cpu_cnn_training_fp32.c
-/// @copydoc cpu_cnn_training_fp32_c
-///
+/// @copybrief cpu_cnn_training_fp32_c
+
 /// @page cpu_cnn_training_fp32_c CNN fp32 training example
-///
 /// This C API example demonstrates how to build an AlexNet model training.
-///
-/// The example implements the AlexNet layers
-/// as numbered primitives (for example, conv1, pool1, conv2).
+/// The example implements a few layers from AlexNet model.
 ///
 /// @include cpu_cnn_training_fp32.c
 

examples/cpu_cnn_training_fp32.cpp

@@ -15,13 +15,11 @@
 *******************************************************************************/
 
 /// @example cpu_cnn_training_fp32.cpp
-/// @copydoc cpu_cnn_training_fp32_cpp
-///
+/// @copybrief cpu_cnn_training_fp32_cpp
+
 /// @page cpu_cnn_training_fp32_cpp CNN fp32 training example
 /// This C++ API example demonstrates how to build an AlexNet model training.
-///
-/// The example implements the AlexNet layers
-/// as numbered primitives (for example, conv1, pool1, conv2).
+/// The example implements a few layers from AlexNet model.
 ///
 /// @include cpu_cnn_training_fp32.cpp
 

examples/cpu_getting_started.cpp

@@ -15,7 +15,10 @@
 *******************************************************************************/
 
 /// @example cpu_getting_started.cpp
-/// Annotated version: @ref cpu_getting_started_cpp
+/// This C++ API example demonstrates basics of Intel MKL-DNN programming
+/// model.
+///
+/// > Annotated version: @ref cpu_getting_started_cpp
 
 #include <iostream>
 #include <sstream>
@@ -25,10 +28,7 @@
 #include <vector>
 
 /// @page cpu_getting_started_cpp Getting started
-///
-/// Full example text: @ref cpu_getting_started.cpp
-///
-/// @section cpu_getting_started_cpp_intro Introduction
+/// > Example code: @ref cpu_getting_started.cpp
 ///
 /// This C++ API example demonstrates basics of Intel MKL-DNN programming
 /// model:

examples/cpu_memory_format_propagation.cpp

@@ -15,17 +15,17 @@
 *******************************************************************************/
 
 /// @example cpu_memory_format_propagation.cpp
-/// Annotated version: @ref cpu_memory_format_propagation_cpp
+/// This example demonstrates memory format propagation, which is critical for
+/// deep learning applications performance.
+///
+/// > Annotated version: @ref cpu_memory_format_propagation_cpp
 
 #include <iostream>
 #include <sstream>
 #include <string>
 
 /// @page cpu_memory_format_propagation_cpp Memory format propagation
-///
-/// Full example text: @ref cpu_memory_format_propagation.cpp
-///
-/// @section cpu_memory_format_propagation_general General notes
+/// > Example code: @ref cpu_memory_format_propagation.cpp
 ///
 /// Format propagation is one of the central notions that needs to be
 /// well-understood to use Intel MKL-DNN correctly.

examples/cpu_performance_profiling.cpp

@@ -14,23 +14,22 @@
 * limitations under the License.
 *******************************************************************************/
 
-
 /// @example cpu_performance_profiling.cpp
-/// Annotated version: @ref cpu_performance_profiling_cpp
+/// This example demonstrates the best practices for application performance
+/// optimizations with Intel MKL-DNN.
+///
+/// > Annotated version: @ref cpu_performance_profiling_cpp
 
 #include <iostream>
 #include <string>
 #include <chrono>
 #include <stdio.h>
 
 /// @page cpu_performance_profiling_cpp Performance Profiling Example
-///
-/// Full example text: @ref cpu_performance_profiling.cpp
-///
-/// @section cpu_performance_profiling_cpp_intro Introduction
+/// > Example code: @ref cpu_performance_profiling.cpp
 ///
 /// This example uses [MKLDNN_VERBOSE](@ref dev_guide_verbose) trace output
-/// to tune Intel(R) MKL-DNN code to align
+/// to tune Intel MKL-DNN code to align
 /// with the [best practices](@ref dev_guide_inference).
 ///
 /// It will assume knowledge of memory formats and their usage in

examples/cpu_rnn_inference_fp32.cpp

@@ -15,12 +15,13 @@
 *******************************************************************************/
 
 /// @example cpu_rnn_inference_fp32.cpp
-/// Annotated version: @ref cpu_rnn_inference_fp32_cpp
-///
+/// @copybrief cpu_rnn_inference_fp32_cpp 
+/// > Annotated version: @ref cpu_rnn_inference_fp32_cpp
+
 /// @page cpu_rnn_inference_fp32_cpp RNN fp32 inference example
-/// Full example text: @ref cpu_rnn_inference_fp32.cpp
+/// This C++ API example demonstrates how to build GNMT model inference.
 ///
-/// This C++ API example demonstrates how to build an GNMT model inference
+/// > Example code: @ref cpu_rnn_inference_fp32.cpp
 ///
 /// For the encoder we use:
 ///  - one primitive for the bidirectional layer of the encoder

examples/cpu_rnn_inference_int8.cpp

@@ -15,11 +15,14 @@
 *******************************************************************************/
 
 /// @example cpu_rnn_inference_int8.cpp
-/// @copydoc cpu_rnn_inference_int8_cpp
-///
+/// @copybrief cpu_rnn_inference_int8_cpp
+/// > Annotated version: @ref cpu_rnn_inference_int8_cpp
+
 /// @page cpu_rnn_inference_int8_cpp RNN int8 inference example
+/// This C++ API example demonstrates how to build GNMT model inference.
+///
+/// > Example code: @ref cpu_rnn_inference_int8.cpp
 ///
-/// This C++ API example demonstrates how to build an GNMT model inference
 /// For the encoder we use:
 ///  - one primitive for the bidirectional layer of the encoder
 ///  - one primitive for all remaining unidirectional layers in the encoder
@@ -29,8 +32,6 @@
 ///    in this example, this primitive computes the states in place.
 ///  - the attention mechanism is implemented separately as there is no support
 ///    for the context vectors in MKL-DNN yet
-///
-/// @include cpu_rnn_inference_int8.cpp
 
 #include <assert.h>
 

examples/cpu_rnn_training_fp32.cpp

@@ -15,10 +15,10 @@
 *******************************************************************************/
 
 /// @example cpu_rnn_training_fp32.cpp
-/// @copydoc cpu_rnn_training_fp32_cpp
+/// @copybrief cpu_rnn_training_fp32_cpp
 ///
 /// @page cpu_rnn_training_fp32_cpp RNN fp32 training example
-/// This C++ API example demonstrates how to build an GNMT model training
+/// This C++ API example demonstrates how to build GNMT model training.
 ///
 /// @include cpu_rnn_training_fp32.cpp
 

examples/gpu_getting_started.c

@@ -15,12 +15,15 @@
 *******************************************************************************/
 
 /// @example gpu_getting_started.c
-/// @copydoc gpu_getting_started_c
-///
+/// @copybrief gpu_getting_started_c
+/// > Annotated version: @ref gpu_getting_started_c
+
 /// @page gpu_getting_started_c Getting started on GPU
-///
 /// This C API example demonstrates programming for Intel(R) Processor
-/// Graphics with Intel MKL-DNN
+/// Graphics with Intel MKL-DNN.
+///
+/// > Example code: @ref gpu_getting_started.c
+///
 /// - How to create Intel MKL-DNN memory objects.
 ///   - How to get data from user's buffer into an Intel MKL-DNN
 ///     memory object.

examples/gpu_getting_started.cpp

@@ -15,13 +15,18 @@
 *******************************************************************************/
 
 /// @example gpu_getting_started.cpp
-/// @copydoc gpu_getting_started_cpp
-///
+/// @copybrief gpu_getting_started_cpp
+/// > Annotated version: @ref gpu_getting_started_cpp
+
+#include <iostream>
+#include <sstream>
+
 /// @page gpu_getting_started_cpp Getting started on GPU
-/// Full example text: @ref gpu_getting_started.cpp
-///
 /// This C++ API example demonstrates programming for Intel(R) Processor
-/// Graphics with Intel(R) MKL-DNN
+/// Graphics with Intel(R) MKL-DNN.
+///
+/// > Example code: @ref gpu_getting_started.cpp
+///
 ///   - How to create Intel MKL-DNN memory objects for both GPU and CPU.
 ///   - How to get data from the user's buffer into an Intel MKL-DNN
 ///     GPU memory object.
@@ -30,8 +35,6 @@
 ///   - How to create Intel MKL-DNN primitives on GPU.
 ///   - How to execute the primitives on GPU.
 ///
-/// @page gpu_getting_started_cpp
-
 /// @section gpu_getting_started_cpp_headers Public headers
 ///
 /// To start using Intel MKL-DNN, we must first include the @ref mkldnn.hpp
@@ -44,9 +47,6 @@
 /// @page gpu_getting_started_cpp
 /// @snippet gpu_getting_started.cpp Prologue
 // [Prologue]
-#include <iostream>
-#include <sstream>
-
 #include "mkldnn.hpp"
 
 // Optional header to access debug functions like `mkldnn_status2str()`
@@ -92,7 +92,6 @@ int find_negative(const memory &mem, const memory::dims adims) {
 /// @section gpu_getting_started_cpp_tutorial gpu_getting_started_tutorial() function
 /// @page gpu_getting_started_cpp
 void gpu_getting_started_tutorial() {
-
     /// @page gpu_getting_started_cpp
     /// @subsection gpu_getting_started_cpp_sub1 Engine and stream
     ///
@@ -248,6 +247,7 @@ void gpu_getting_started_tutorial() {
     // [Check the results]
 }
 
+/// @page gpu_getting_started_cpp
 /// @section gpu_getting_started_cpp_main main() function
 ///
 /// We now just call everything we prepared earlier.
@@ -257,8 +257,8 @@ void gpu_getting_started_tutorial() {
 /// The Intel MKL-DNN C++ API throws exceptions of type @ref mkldnn::error,
 /// which contains the error status (of type @ref mkldnn_status_t) and a
 /// human-readable error message accessible through regular `what()` method.
-/// @page gpu_getting_started_cpp
 /// @snippet gpu_getting_started.cpp Main
+
 // [Main]
 int main(int argc, char **argv) {
     try {
@@ -276,6 +276,7 @@ int main(int argc, char **argv) {
     return 0;
 }
 // [Main]
+
 /// <b></b>
 ///
 /// Upon compiling and running the example, the output should be just: