Updated sample files documentation inclusions

doc/CMakeLists.txt

@@ -143,7 +143,6 @@ if(BUILD_DOCS AND DOXYGEN_FOUND)
 
   # TODO: do not store downloadable samples, but give github link instead
   add_custom_target(doxygen
-    COMMAND "${CMAKE_COMMAND}" -E copy_directory "${CMAKE_SOURCE_DIR}/samples" "${CMAKE_DOXYGEN_OUTPUT_PATH}/html/samples"
     COMMAND "${CMAKE_COMMAND}" -E copy "${CMAKE_CURRENT_SOURCE_DIR}/pattern.png" "${CMAKE_DOXYGEN_OUTPUT_PATH}/html"
     COMMAND "${CMAKE_COMMAND}" -E copy "${CMAKE_CURRENT_SOURCE_DIR}/acircles_pattern.png" "${CMAKE_DOXYGEN_OUTPUT_PATH}/html"
     COMMAND ${DOXYGEN_EXECUTABLE} ${doxyfile}

doc/packaging.txt

@@ -1,17 +0,0 @@
-
-INSTRUCTIONS TO BUILD WIN32 PACKAGES WITH CMAKE+CPACK
-------------------------------------------------------
-
-- Install NSIS.
-- Generate OpenCV solutions for MSVC using CMake as usual.
-- In cmake-gui:
-    - Mark BUILD_PACKAGE
-    - Mark BUILD_EXAMPLES (If examples are desired to be shipped as binaries...)
-    - Unmark ENABLE_OPENMP, since this feature seems to have some issues yet...
-    - Mark INSTALL_*_EXAMPLES
-- Open the OpenCV solution and build ALL in Debug and Release.
-- Build PACKAGE, from the Release configuration. An NSIS installer package will be
-  created with both release and debug LIBs and DLLs.
-
-
-Jose Luis Blanco, 2009/JUL/29

doc/tutorials/calib3d/camera_calibration/camera_calibration.markdown

@@ -77,13 +77,13 @@ Source code
 
 You may also find the source code in the `samples/cpp/tutorial_code/calib3d/camera_calibration/`
 folder of the OpenCV source library or [download it from here
-](samples/cpp/tutorial_code/calib3d/camera_calibration/camera_calibration.cpp). The program has a
+](https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/calib3d/camera_calibration/camera_calibration.cpp). The program has a
 single argument: the name of its configuration file. If none is given then it will try to open the
 one named "default.xml". [Here's a sample configuration file
-](samples/cpp/tutorial_code/calib3d/camera_calibration/in_VID5.xml) in XML format. In the
+](https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/calib3d/camera_calibration/in_VID5.xml) in XML format. In the
 configuration file you may choose to use camera as an input, a video file or an image list. If you
 opt for the last one, you will need to create a configuration file where you enumerate the images to
-use. Here's [an example of this ](samples/cpp/tutorial_code/calib3d/camera_calibration/VID5.xml).
+use. Here's [an example of this ](https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/calib3d/camera_calibration/VID5.xml).
 The important part to remember is that the images need to be specified using the absolute path or
 the relative one from your application's working directory. You may find all this in the samples
 directory mentioned above.

doc/tutorials/core/discrete_fourier_transform/discrete_fourier_transform.markdown

@@ -15,21 +15,14 @@ Source code
 -----------
 
 You can [download this from here
-](samples/cpp/tutorial_code/core/discrete_fourier_transform/discrete_fourier_transform.cpp) or
+](https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/core/discrete_fourier_transform/discrete_fourier_transform.cpp) or
 find it in the
 `samples/cpp/tutorial_code/core/discrete_fourier_transform/discrete_fourier_transform.cpp` of the
 OpenCV source code library.
 
 Here's a sample usage of @ref cv::dft() :
 
-@dontinclude cpp/tutorial_code/core/discrete_fourier_transform/discrete_fourier_transform.cpp
-@until highgui.hpp
-@skipline iostream
-@skip main
-@until {
-@skip filename
-@until return 0;
-@until }
+@includelineno cpp/tutorial_code/core/discrete_fourier_transform/discrete_fourier_transform.cpp
 
 Explanation
 -----------
@@ -147,7 +140,7 @@ An application idea would be to determine the geometrical orientation present in
 example, let us find out if a text is horizontal or not? Looking at some text you'll notice that the
 text lines sort of form also horizontal lines and the letters form sort of vertical lines. These two
 main components of a text snippet may be also seen in case of the Fourier transform. Let us use
-[this horizontal ](samples/data/imageTextN.png) and [this rotated](samples/data/imageTextR.png)
+[this horizontal ](https://github.com/Itseez/opencv/tree/master/samples/data/imageTextN.png) and [this rotated](https://github.com/Itseez/opencv/tree/master/samples/data/imageTextR.png)
 image about a text.
 
 In case of the horizontal text:

doc/tutorials/core/file_input_output_with_xml_yml/file_input_output_with_xml_yml.markdown

@@ -16,18 +16,13 @@ Source code
 -----------
 
 You can [download this from here
-](samples/cpp/tutorial_code/core/file_input_output/file_input_output.cpp) or find it in the
+](https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/core/file_input_output/file_input_output.cpp) or find it in the
 `samples/cpp/tutorial_code/core/file_input_output/file_input_output.cpp` of the OpenCV source code
 library.
 
 Here's a sample code of how to achieve all the stuff enumerated at the goal list.
 
-@dontinclude cpp/tutorial_code/core/file_input_output/file_input_output.cpp
-
-@until std;
-@skip class MyData
-@until return 0;
-@until }
+@includelineno cpp/tutorial_code/core/file_input_output/file_input_output.cpp
 
 Explanation
 -----------

doc/tutorials/core/how_to_scan_images/how_to_scan_images.markdown

@@ -51,7 +51,7 @@ three major ways of going through an image pixel by pixel. To make things a litt
 will make the scanning for each image using all of these methods, and print out how long it took.
 
 You can download the full source code [here
-](samples/cpp/tutorial_code/core/how_to_scan_images/how_to_scan_images.cpp) or look it up in
+](https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/core/how_to_scan_images/how_to_scan_images.cpp) or look it up in
 the samples directory of OpenCV at the cpp tutorial code for the core section. Its basic usage is:
 @code{.bash}
 how_to_scan_images imageName.jpg intValueToReduce [G]
@@ -59,10 +59,7 @@ how_to_scan_images imageName.jpg intValueToReduce [G]
 The final argument is optional. If given the image will be loaded in gray scale format, otherwise
 the RGB color way is used. The first thing is to calculate the lookup table.
 
-@dontinclude cpp/tutorial_code/core/how_to_scan_images/how_to_scan_images.cpp
-
-@skip int divideWith
-@until table[i]
+@snippet how_to_scan_images.cpp dividewith
 
 Here we first use the C++ *stringstream* class to convert the third command line argument from text
 to an integer format. Then we use a simple look and the upper formula to calculate the lookup table.
@@ -107,9 +104,7 @@ The efficient way
 When it comes to performance you cannot beat the classic C style operator[] (pointer) access.
 Therefore, the most efficient method we can recommend for making the assignment is:
 
-@skip Mat& ScanImageAndReduceC
-@until return
-@until }
+@snippet how_to_scan_images.cpp scan-c
 
 Here we basically just acquire a pointer to the start of each row and go through it until it ends.
 In the special case that the matrix is stored in a continues manner we only need to request the
@@ -141,9 +136,7 @@ considered a safer way as it takes over these tasks from the user. All you need
 begin and the end of the image matrix and then just increase the begin iterator until you reach the
 end. To acquire the value *pointed* by the iterator use the \* operator (add it before it).
 
-@skip ScanImageAndReduceIterator
-@until return
-@until }
+@snippet how_to_scan_images.cpp scan-iterator
 
 In case of color images we have three uchar items per column. This may be considered a short vector
 of uchar items, that has been baptized in OpenCV with the *Vec3b* name. To access the n-th sub
@@ -161,9 +154,7 @@ what type we are looking at the image. It's no different here as you need manual
 type to use at the automatic lookup. You can observe this in case of the gray scale images for the
 following source code (the usage of the + @ref cv::at() function):
 
-@skip ScanImageAndReduceRandomAccess
-@until return
-@until }
+@snippet how_to_scan_images.cpp scan-random
 
 The functions takes your input type and coordinates and calculates on the fly the address of the
 queried item. Then returns a reference to that. This may be a constant when you *get* the value and
@@ -192,14 +183,11 @@ OpenCV has a function that makes the modification without the need from you to w
 the image. We use the @ref cv::LUT() function of the core module. First we build a Mat type of the
 lookup table:
 
-@dontinclude cpp/tutorial_code/core/how_to_scan_images/how_to_scan_images.cpp
-
-@skip Mat lookUpTable
-@until p[i] = table[i]
+@snippet how_to_scan_images.cpp table-init
 
 Finally call the function (I is our input image and J the output one):
 
-@skipline LUT
+@snippet how_to_scan_images.cpp table-use
 
 Performance Difference
 ----------------------

doc/tutorials/core/how_to_use_ippa_conversion/how_to_use_ippa_conversion.markdown

@@ -16,7 +16,7 @@ Code
 
 You may also find the source code in the
 `samples/cpp/tutorial_code/core/ippasync/ippasync_sample.cpp` file of the OpenCV source library or
-download it from [here](samples/cpp/tutorial_code/core/ippasync/ippasync_sample.cpp).
+download it from [here](https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/core/ippasync/ippasync_sample.cpp).
 
 @includelineno cpp/tutorial_code/core/ippasync/ippasync_sample.cpp
 

doc/tutorials/core/interoperability_with_OpenCV_1/interoperability_with_OpenCV_1.markdown

@@ -85,7 +85,7 @@ L = Mat(pI);
 A case study
 ------------
 
-Now that you have the basics done [here's](samples/cpp/tutorial_code/core/interoperability_with_OpenCV_1/interoperability_with_OpenCV_1.cpp)
+Now that you have the basics done [here's](https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/core/interoperability_with_OpenCV_1/interoperability_with_OpenCV_1.cpp)
 an example that mixes the usage of the C interface with the C++ one. You will also find it in the
 sample directory of the OpenCV source code library at the
 `samples/cpp/tutorial_code/core/interoperability_with_OpenCV_1/interoperability_with_OpenCV_1.cpp` .
@@ -93,18 +93,13 @@ To further help on seeing the difference the programs supports two modes: one mi
 one pure C++. If you define the *DEMO_MIXED_API_USE* you'll end up using the first. The program
 separates the color planes, does some modifications on them and in the end merge them back together.
 
-@dontinclude cpp/tutorial_code/core/interoperability_with_OpenCV_1/interoperability_with_OpenCV_1.cpp
-@until namespace cv
-@skip ifdef
-@until endif
-@skip main
-@until endif
+@snippet interoperability_with_OpenCV_1.cpp head
+@snippet interoperability_with_OpenCV_1.cpp start
 
 Here you can observe that with the new structure we have no pointer problems, although it is
 possible to use the old functions and in the end just transform the result to a *Mat* object.
 
-@skip convert image
-@until split
+@snippet interoperability_with_OpenCV_1.cpp new
 
 Because, we want to mess around with the images luma component we first convert from the default RGB
 to the YUV color space and then split the result up into separate planes. Here the program splits:
@@ -114,8 +109,7 @@ image some Gaussian noise and then mix together the channels according to some f
 
 The scanning version looks like:
 
-@skip #if 1
-@until #else
+@snippet interoperability_with_OpenCV_1.cpp scanning
 
 Here you can observe that we may go through all the pixels of an image in three fashions: an
 iterator, a C pointer and an individual element access style. You can read a more in-depth
@@ -123,14 +117,12 @@ description of these in the @ref tutorial_how_to_scan_images tutorial. Convertin
 names is easy. Just remove the cv prefix and use the new *Mat* data structure. Here's an example of
 this by using the weighted addition function:
 
-@until planes[0]
-@until endif
+@snippet interoperability_with_OpenCV_1.cpp noisy
 
 As you may observe the *planes* variable is of type *Mat*. However, converting from *Mat* to
 *IplImage* is easy and made automatically with a simple assignment operator.
 
-@skip merge(planes
-@until #endif
+@snippet interoperability_with_OpenCV_1.cpp end
 
 The new *imshow* highgui function accepts both the *Mat* and *IplImage* data structures. Compile and
 run the program and if the first image below is your input you may get either the first or second as
@@ -140,7 +132,7 @@ output:
 
 You may observe a runtime instance of this on the [YouTube
 here](https://www.youtube.com/watch?v=qckm-zvo31w) and you can [download the source code from here
-](samples/cpp/tutorial_code/core/interoperability_with_OpenCV_1/interoperability_with_OpenCV_1.cpp)
+](https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/core/interoperability_with_OpenCV_1/interoperability_with_OpenCV_1.cpp)
 or find it in the
 `samples/cpp/tutorial_code/core/interoperability_with_OpenCV_1/interoperability_with_OpenCV_1.cpp`
 of the OpenCV source code library.

doc/tutorials/core/mat-mask-operations/mat_mask_operations.markdown

@@ -133,7 +133,7 @@ For example:
 ![](images/resultMatMaskFilter2D.png)
 
 You can download this source code from [here
-](samples/cpp/tutorial_code/core/mat_mask_operations/mat_mask_operations.cpp) or look in the
+](https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/core/mat_mask_operations/mat_mask_operations.cpp) or look in the
 OpenCV source code libraries sample directory at
 `samples/cpp/tutorial_code/core/mat_mask_operations/mat_mask_operations.cpp`.
 

doc/tutorials/core/mat_the_basic_image_container/mat_the_basic_image_container.markdown

@@ -144,16 +144,13 @@ file by using the @ref cv::imwrite() function. However, for debugging purposes i
 convenient to see the actual values. You can do this using the \<\< operator of *Mat*. Be aware that
 this only works for two dimensional matrices.
 
-@dontinclude cpp/tutorial_code/core/mat_the_basic_image_container/mat_the_basic_image_container.cpp
-
 Although *Mat* works really well as an image container, it is also a general matrix class.
 Therefore, it is possible to create and manipulate multidimensional matrices. You can create a Mat
 object in multiple ways:
 
 -   @ref cv::Mat::Mat Constructor
 
-    @skip Mat M(2
-    @until cout
+    @snippet mat_the_basic_image_container.cpp constructor
 
     ![](images/MatBasicContainerOut1.png)
 
@@ -162,7 +159,7 @@ object in multiple ways:
     Then we need to specify the data type to use for storing the elements and the number of channels
     per matrix point. To do this we have multiple definitions constructed according to the following
     convention:
-    @code{.cpp}
+    @code
     CV_[The number of bits per item][Signed or Unsigned][Type Prefix]C[The channel number]
     @endcode
     For instance, *CV_8UC3* means we use unsigned char types that are 8 bit long and each pixel has
@@ -173,18 +170,15 @@ object in multiple ways:
 
 -   Use C/C++ arrays and initialize via constructor
 
-    @skip int sz
-    @until Mat L
+    @snippet mat_the_basic_image_container.cpp init
 
     The upper example shows how to create a matrix with more than two dimensions. Specify its
     dimension, then pass a pointer containing the size for each dimension and the rest remains the
     same.
 
 -   @ref cv::Mat::create function:
-    @code
-    M.create(4,4, CV_8UC(2));
-    cout << "M = "<< endl << " "  << M << endl << endl;
-    @endcode
+
+    @snippet mat_the_basic_image_container.cpp create
 
     ![](images/MatBasicContainerOut2.png)
 
@@ -194,30 +188,26 @@ object in multiple ways:
 -   MATLAB style initializer: @ref cv::Mat::zeros , @ref cv::Mat::ones , @ref cv::Mat::eye . Specify size and
     data type to use:
 
-    @skip Mat E
-    @until cout
+    @snippet mat_the_basic_image_container.cpp matlab
 
     ![](images/MatBasicContainerOut3.png)
 
 -   For small matrices you may use comma separated initializers:
 
-    @skip Mat C
-    @until cout
+    @snippet mat_the_basic_image_container.cpp comma
 
     ![](images/MatBasicContainerOut6.png)
 
 -   Create a new header for an existing *Mat* object and @ref cv::Mat::clone or @ref cv::Mat::copyTo it.
 
-    @skip Mat RowClone
-    @until cout
+    @snippet mat_the_basic_image_container.cpp clone
 
     ![](images/MatBasicContainerOut7.png)
 
     @note
     You can fill out a matrix with random values using the @ref cv::randu() function. You need to
     give the lower and upper value for the random values:
-    @skip Mat R
-    @until randu
+    @snippet mat_the_basic_image_container.cpp random
 
 
 Output formatting
@@ -227,25 +217,23 @@ In the above examples you could see the default formatting option. OpenCV, howev
 format your matrix output:
 
 -   Default
-    @skipline (default)
+    @snippet mat_the_basic_image_container.cpp out-default
     ![](images/MatBasicContainerOut8.png)
 
 -   Python
-    @skipline (python)
+    @snippet mat_the_basic_image_container.cpp out-python
     ![](images/MatBasicContainerOut16.png)
 
 -   Comma separated values (CSV)
-    @skipline (csv)
+    @snippet mat_the_basic_image_container.cpp out-csv
     ![](images/MatBasicContainerOut10.png)
 
 -   Numpy
-    @code
-    cout << "R (numpy)   = " << endl << format(R, Formatter::FMT_NUMPY ) << endl << endl;
-    @endcode
+    @snippet mat_the_basic_image_container.cpp out-numpy
     ![](images/MatBasicContainerOut9.png)
 
 -   C
-    @skipline (c)
+    @snippet mat_the_basic_image_container.cpp out-c
     ![](images/MatBasicContainerOut11.png)
 
 Output of other common items
@@ -254,27 +242,23 @@ Output of other common items
 OpenCV offers support for output of other common OpenCV data structures too via the \<\< operator:
 
 -   2D Point
-    @skip Point2f P
-    @until cout
+    @snippet mat_the_basic_image_container.cpp out-point2
     ![](images/MatBasicContainerOut12.png)
 
 -   3D Point
-    @skip Point3f P3f
-    @until cout
+    @snippet mat_the_basic_image_container.cpp out-point3
     ![](images/MatBasicContainerOut13.png)
 
 -   std::vector via cv::Mat
-    @skip vector<float> v
-    @until cout
+    @snippet mat_the_basic_image_container.cpp out-vector
     ![](images/MatBasicContainerOut14.png)
 
 -   std::vector of points
-    @skip vector<Point2f> vPoints
-    @until cout
+    @snippet mat_the_basic_image_container.cpp out-vector-points
     ![](images/MatBasicContainerOut15.png)
 
 Most of the samples here have been included in a small console application. You can download it from
-[here](samples/cpp/tutorial_code/core/mat_the_basic_image_container/mat_the_basic_image_container.cpp)
+[here](https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/core/mat_the_basic_image_container/mat_the_basic_image_container.cpp)
 or in the core section of the cpp samples.
 
 You can also find a quick video demonstration of this on

doc/tutorials/gpu/gpu-basics-similarity/gpu_basics_similarity.markdown

@@ -24,7 +24,7 @@ The source code
 
 You may also find the source code and these video file in the
 `samples/cpp/tutorial_code/gpu/gpu-basics-similarity/gpu-basics-similarity` folder of the OpenCV
-source library or download it from [here](samples/cpp/tutorial_code/gpu/gpu-basics-similarity/gpu-basics-similarity.cpp).
+source library or download it from [here](https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/gpu/gpu-basics-similarity/gpu-basics-similarity.cpp).
 The full source code is quite long (due to the controlling of the application via the command line
 arguments and performance measurement). Therefore, to avoid cluttering up these sections with those
 you'll find here only the functions itself.
@@ -32,37 +32,19 @@ you'll find here only the functions itself.
 The PSNR returns a float number, that if the two inputs are similar between 30 and 50 (higher is
 better).
 
-@dontinclude samples/cpp/tutorial_code/gpu/gpu-basics-similarity/gpu-basics-similarity.cpp
-
-@skip struct BufferPSNR
-@until };
-
-@skip double getPSNR(
-@until return psnr;
-@until }
-@until }
-
-@skip double getPSNR_CUDA(
-@until return psnr;
-@until }
-@until }
+@snippet samples/cpp/tutorial_code/gpu/gpu-basics-similarity/gpu-basics-similarity.cpp getpsnr
+@snippet samples/cpp/tutorial_code/gpu/gpu-basics-similarity/gpu-basics-similarity.cpp getpsnrcuda
+@snippet samples/cpp/tutorial_code/gpu/gpu-basics-similarity/gpu-basics-similarity.cpp psnr
+@snippet samples/cpp/tutorial_code/gpu/gpu-basics-similarity/gpu-basics-similarity.cpp getpsnropt
 
 The SSIM returns the MSSIM of the images. This is too a float number between zero and one (higher is
 better), however we have one for each channel. Therefore, we return a *Scalar* OpenCV data
 structure:
 
-@dontinclude samples/cpp/tutorial_code/gpu/gpu-basics-similarity/gpu-basics-similarity.cpp
-
-@skip struct BufferMSSIM
-@until };
-
-@skip Scalar getMSSIM(
-@until return mssim;
-@until }
-
-@skip Scalar getMSSIM_CUDA_optimized(
-@until return mssim;
-@until }
+@snippet samples/cpp/tutorial_code/gpu/gpu-basics-similarity/gpu-basics-similarity.cpp getssim
+@snippet samples/cpp/tutorial_code/gpu/gpu-basics-similarity/gpu-basics-similarity.cpp getssimcuda
+@snippet samples/cpp/tutorial_code/gpu/gpu-basics-similarity/gpu-basics-similarity.cpp ssim
+@snippet samples/cpp/tutorial_code/gpu/gpu-basics-similarity/gpu-basics-similarity.cpp getssimopt
 
 How to do it? - The GPU
 -----------------------

doc/tutorials/highgui/video-input-psnr-ssim/video_input_psnr_ssim.markdown

@@ -20,19 +20,12 @@ As a test case where to show off these using OpenCV I've created a small program
 video files and performs a similarity check between them. This is something you could use to check
 just how well a new video compressing algorithms works. Let there be a reference (original) video
 like [this small Megamind clip
-](samples/cpp/tutorial_code/HighGUI/video-input-psnr-ssim/video/Megamind.avi) and [a compressed
-version of it ](samples/cpp/tutorial_code/HighGUI/video-input-psnr-ssim/video/Megamind_bugy.avi).
+](https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/HighGUI/video-input-psnr-ssim/video/Megamind.avi) and [a compressed
+version of it ](https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/HighGUI/video-input-psnr-ssim/video/Megamind_bugy.avi).
 You may also find the source code and these video file in the
 `samples/cpp/tutorial_code/HighGUI/video-input-psnr-ssim/` folder of the OpenCV source library.
 
-@dontinclude cpp/tutorial_code/HighGUI/video-input-psnr-ssim/video-input-psnr-ssim.cpp
-
-@until Scalar getMSSIM
-@skip main
-@until {
-@skip if
-@until return mssim;
-@until }
+@includelineno cpp/tutorial_code/HighGUI/video-input-psnr-ssim/video-input-psnr-ssim.cpp
 
 How to read a video stream (online-camera or offline-file)?
 -----------------------------------------------------------

doc/tutorials/highgui/video-write/video_write.markdown

@@ -31,7 +31,7 @@ The source code
 
 You may also find the source code and these video file in the
 `samples/cpp/tutorial_code/highgui/video-write/` folder of the OpenCV source library or [download it
-from here ](samples/cpp/tutorial_code/HighGUI/video-write/video-write.cpp).
+from here ](https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/HighGUI/video-write/video-write.cpp).
 
 @includelineno cpp/tutorial_code/HighGUI/video-write/video-write.cpp
 

doc/tutorials/introduction/display_image/display_image.markdown

@@ -21,8 +21,6 @@ Download the source code from
 Explanation
 -----------
 
-@dontinclude cpp/tutorial_code/introduction/display_image/display_image.cpp
-
 In OpenCV 2 we have multiple modules. Each one takes care of a different area or approach towards
 image processing. You could already observe this in the structure of the user guide of these
 tutorials itself. Before you use any of them you first need to include the header files where the
@@ -33,25 +31,24 @@ You'll almost always end up using the:
 -   *core* section, as here are defined the basic building blocks of the library
 -   *highgui* module, as this contains the functions for input and output operations
 
-@until <string>
+@snippet cpp/tutorial_code/introduction/display_image/display_image.cpp includes
 
 We also include the *iostream* to facilitate console line output and input. To avoid data structure
 and function name conflicts with other libraries, OpenCV has its own namespace: *cv*. To avoid the
 need appending prior each of these the *cv::* keyword you can import the namespace in the whole file
 by using the lines:
 
-@line using namespace cv
+@snippet cpp/tutorial_code/introduction/display_image/display_image.cpp namespace
 
 This is true for the STL library too (used for console I/O). Now, let's analyze the *main* function.
 We start up assuring that we acquire a valid image name argument from the command line. Otherwise
 take a picture by default: "HappyFish.jpg".
 
-@skip string
-@until }
+@snippet cpp/tutorial_code/introduction/display_image/display_image.cpp load
 
 Then create a *Mat* object that will store the data of the loaded image.
 
-@skipline Mat
+@snippet cpp/tutorial_code/introduction/display_image/display_image.cpp mat
 
 Now we call the @ref cv::imread function which loads the image name specified by the first argument
 (*argv[1]*). The second argument specifies the format in what we want the image. This may be:
@@ -60,7 +57,7 @@ Now we call the @ref cv::imread function which loads the image name specified by
 -   IMREAD_GRAYSCALE ( 0) loads the image as an intensity one
 -   IMREAD_COLOR (\>0) loads the image in the RGB format
 
-@skipline image = imread
+@snippet cpp/tutorial_code/introduction/display_image/display_image.cpp imread
 
 @note
    OpenCV offers support for the image formats Windows bitmap (bmp), portable image formats (pbm,
@@ -82,18 +79,18 @@ the image it contains from a size point of view. It may be:
     would like the image to keep its aspect ratio (*WINDOW_KEEPRATIO*) or not
     (*WINDOW_FREERATIO*).
 
-@skipline namedWindow
+@snippet cpp/tutorial_code/introduction/display_image/display_image.cpp window
 
 Finally, to update the content of the OpenCV window with a new image use the @ref cv::imshow
 function. Specify the OpenCV window name to update and the image to use during this operation:
 
-@skipline imshow
+@snippet cpp/tutorial_code/introduction/display_image/display_image.cpp imshow
 
 Because we want our window to be displayed until the user presses a key (otherwise the program would
 end far too quickly), we use the @ref cv::waitKey function whose only parameter is just how long
 should it wait for a user input (measured in milliseconds). Zero means to wait forever.
 
-@skipline waitKey
+@snippet cpp/tutorial_code/introduction/display_image/display_image.cpp wait
 
 Result
 ------
@@ -101,7 +98,7 @@ Result
 -   Compile your code and then run the executable giving an image path as argument. If you're on
     Windows the executable will of course contain an *exe* extension too. Of course assure the image
     file is near your program file.
-    @code{.bash}
+    @code{.sh}
     ./DisplayImage HappyFish.jpg
     @endcode
 -   You should get a nice window as the one shown below:

doc/tutorials/introduction/windows_visual_studio_Opencv/windows_visual_studio_Opencv.markdown

@@ -189,12 +189,11 @@ Test it!
 --------
 
 Now to try this out download our little test [source code
-](samples/cpp/tutorial_code/introduction/windows_visual_studio_Opencv/introduction_windows_vs.cpp)
+](https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/introduction/windows_visual_studio_Opencv/introduction_windows_vs.cpp)
 or get it from the sample code folder of the OpenCV sources. Add this to your project and build it.
 Here's its content:
 
-@includelineno
-cpp/tutorial_code/introduction/windows_visual_studio_Opencv/introduction_windows_vs.cpp
+@includelineno cpp/tutorial_code/introduction/windows_visual_studio_Opencv/introduction_windows_vs.cpp
 
 You can start a Visual Studio build from two places. Either inside from the *IDE* (keyboard
 combination: Control-F5) or by navigating to your build directory and start the application with a
@@ -206,7 +205,7 @@ the *IDE* the console window will not close once finished. It will wait for a ke
 This is important to remember when you code inside the code open and save commands. You're resources
 will be saved ( and queried for at opening!!!) relatively to your working directory. This is unless
 you give a full, explicit path as parameter for the I/O functions. In the code above we open [this
-OpenCV logo](samples/data/opencv-logo.png). Before starting up the application make sure you place
+OpenCV logo](https://github.com/Itseez/opencv/tree/master/samples/data/opencv-logo.png). Before starting up the application make sure you place
 the image file in your current working directory. Modify the image file name inside the code to try
 it out on other images too. Run it and voil á:
 

doc/tutorials/ml/non_linear_svms/non_linear_svms.markdown

@@ -91,7 +91,7 @@ Source Code
 
 You may also find the source code and these video file in the
 `samples/cpp/tutorial_code/gpu/non_linear_svms/non_linear_svms` folder of the OpenCV source library
-or [download it from here ](samples/cpp/tutorial_code/ml/non_linear_svms/non_linear_svms.cpp).
+or [download it from here ](https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/ml/non_linear_svms/non_linear_svms.cpp).
 
 @includelineno cpp/tutorial_code/ml/non_linear_svms/non_linear_svms.cpp
 

doc/tutorials/video/background_subtraction/background_subtraction.markdown

@@ -45,7 +45,7 @@ Two different methods are used to generate two foreground masks:
 -#  @ref cv::BackgroundSubtractorMOG2
 
 The results as well as the input data are shown on the screen.
-The source file can be downloaded [here ](samples/cpp/tutorial_code/video/bg_sub.cpp).
+The source file can be downloaded [here ](https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/video/bg_sub.cpp).
 
 @includelineno samples/cpp/tutorial_code/video/bg_sub.cpp
 

doc/tutorials/viz/creating_widgets/creating_widgets.markdown

@@ -12,7 +12,7 @@ In this tutorial you will learn how to
 Code
 ----
 
-You can download the code from [here ](samples/cpp/tutorial_code/viz/creating_widgets.cpp).
+You can download the code from [here ](https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/viz/creating_widgets.cpp).
 @includelineno samples/cpp/tutorial_code/viz/creating_widgets.cpp
 
 Explanation

doc/tutorials/viz/launching_viz/launching_viz.markdown

@@ -14,7 +14,7 @@ In this tutorial you will learn how to
 Code
 ----
 
-You can download the code from [here ](samples/cpp/tutorial_code/viz/launching_viz.cpp).
+You can download the code from [here ](https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/viz/launching_viz.cpp).
 @includelineno samples/cpp/tutorial_code/viz/launching_viz.cpp
 
 Explanation

doc/tutorials/viz/transformations/transformations.markdown

@@ -13,7 +13,7 @@ In this tutorial you will learn how to
 Code
 ----
 
-You can download the code from [here ](samples/cpp/tutorial_code/viz/transformations.cpp).
+You can download the code from [here ](https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/viz/transformations.cpp).
 @includelineno samples/cpp/tutorial_code/viz/transformations.cpp
 
 Explanation

doc/tutorials/viz/widget_pose/widget_pose.markdown

@@ -13,7 +13,7 @@ In this tutorial you will learn how to
 Code
 ----
 
-You can download the code from [here ](samples/cpp/tutorial_code/viz/widget_pose.cpp).
+You can download the code from [here ](https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/viz/widget_pose.cpp).
 @includelineno samples/cpp/tutorial_code/viz/widget_pose.cpp
 
 Explanation

modules/core/include/opencv2/core/mat.hpp

@@ -637,9 +637,7 @@ sub-matrices.
     Partial yet very common cases of this *user-allocated data* case are conversions from CvMat and
     IplImage to Mat. For this purpose, there is function cv::cvarrToMat taking pointers to CvMat or
     IplImage and the optional flag indicating whether to copy the data or not.
-    @dontinclude samples/cpp/image.cpp
-    @skip Ptr<IplImage> iplimg
-    @until is converted, while the data is shared
+    @snippet samples/cpp/image.cpp iplimage
 
 - Use MATLAB-style array initializers, zeros(), ones(), eye(), for example:
 @code

samples/cpp/image.cpp

@@ -30,6 +30,7 @@ int main( int argc, char** argv )
     help();
     const char* imagename = argc > 1 ? argv[1] : "../data/lena.jpg";
 #if DEMO_MIXED_API_USE
+    //! [iplimage]
     Ptr<IplImage> iplimg(cvLoadImage(imagename)); // Ptr<T> is safe ref-counting pointer class
     if(!iplimg)
     {
@@ -39,6 +40,7 @@ int main( int argc, char** argv )
     Mat img = cv::cvarrToMat(iplimg); // cv::Mat replaces the CvMat and IplImage, but it's easy to convert
     // between the old and the new data structures (by default, only the header
     // is converted, while the data is shared)
+    //! [iplimage]
 #else
     Mat img = imread(imagename); // the newer cvLoadImage alternative, MATLAB-style function
     if(img.empty())

samples/cpp/tutorial_code/core/how_to_scan_images/how_to_scan_images.cpp

@@ -47,6 +47,7 @@ int main( int argc, char* argv[])
         return -1;
     }
 
+    //! [dividewith]
     int divideWith = 0; // convert our input string to number - C++ style
     stringstream s;
     s << argv[2];
@@ -60,6 +61,7 @@ int main( int argc, char* argv[])
     uchar table[256];
     for (int i = 0; i < 256; ++i)
        table[i] = (uchar)(divideWith * (i/divideWith));
+    //! [dividewith]
 
     const int times = 100;
     double t;
@@ -106,15 +108,19 @@ int main( int argc, char* argv[])
     cout << "Time of reducing with the on-the-fly address generation - at function (averaged for "
         << times << " runs): " << t << " milliseconds."<< endl;
 
+    //! [table-init]
     Mat lookUpTable(1, 256, CV_8U);
     uchar* p = lookUpTable.ptr();
     for( int i = 0; i < 256; ++i)
         p[i] = table[i];
+    //! [table-init]
 
     t = (double)getTickCount();
 
     for (int i = 0; i < times; ++i)
+        //! [table-use]
         LUT(I, lookUpTable, J);
+        //! [table-use]
 
     t = 1000*((double)getTickCount() - t)/getTickFrequency();
     t /= times;
@@ -124,6 +130,7 @@ int main( int argc, char* argv[])
     return 0;
 }
 
+//! [scan-c]
 Mat& ScanImageAndReduceC(Mat& I, const uchar* const table)
 {
     // accept only char type matrices
@@ -152,7 +159,9 @@ Mat& ScanImageAndReduceC(Mat& I, const uchar* const table)
     }
     return I;
 }
+//! [scan-c]
 
+//! [scan-iterator]
 Mat& ScanImageAndReduceIterator(Mat& I, const uchar* const table)
 {
     // accept only char type matrices
@@ -182,7 +191,9 @@ Mat& ScanImageAndReduceIterator(Mat& I, const uchar* const table)
 
     return I;
 }
+//! [scan-iterator]
 
+//! [scan-random]
 Mat& ScanImageAndReduceRandomAccess(Mat& I, const uchar* const table)
 {
     // accept only char type matrices
@@ -216,3 +227,4 @@ Mat& ScanImageAndReduceRandomAccess(Mat& I, const uchar* const table)
 
     return I;
 }
+//! [scan-random]

samples/cpp/tutorial_code/core/interoperability_with_OpenCV_1/interoperability_with_OpenCV_1.cpp

@@ -1,3 +1,4 @@
+//! [head]
 #include <stdio.h>
 #include <iostream>
 
@@ -9,6 +10,7 @@
 
 using namespace cv;  // The new C++ interface API is inside this namespace. Import it.
 using namespace std;
+//! [head]
 
 static void help( char* progName)
 {
@@ -20,6 +22,7 @@ static void help( char* progName)
         << progName << " [image-name Default: ../data/lena.jpg]"                   << endl << endl;
 }
 
+//! [start]
 // comment out the define to use only the latest C++ API
 #define DEMO_MIXED_API_USE
 
@@ -49,15 +52,19 @@ int main( int argc, char** argv )
         return -1;
     }
 #endif
+//! [start]
 
+    //! [new]
     // convert image to YUV color space. The output image will be created automatically.
     Mat I_YUV;
     cvtColor(I, I_YUV, COLOR_BGR2YCrCb);
 
     vector<Mat> planes;    // Use the STL's vector structure to store multiple Mat objects
     split(I_YUV, planes);  // split the image into separate color planes (Y U V)
+    //! [new]
 
 #if 1 // change it to 0 if you want to see a blurred and noisy version of this processing
+    //! [scanning]
     // Mat scanning
     // Method 1. process Y plane using an iterator
     MatIterator_<uchar> it = planes[0].begin<uchar>(), it_end = planes[0].end<uchar>();
@@ -80,9 +87,11 @@ int main( int argc, char** argv )
             Vxy =        saturate_cast<uchar>((Vxy-128)/2 + 128);
         }
     }
+    //! [scanning]
 
 #else
 
+    //! [noisy]
     Mat noisyI(I.size(), CV_8U);           // Create a matrix of the specified size and type
 
     // Fills the matrix with normally distributed random values (around number with deviation off).
@@ -117,13 +126,14 @@ int main( int argc, char** argv )
 
     // Mat::mul replaces cvMul(). Again, no temporary arrays are created in case of simple expressions.
     planes[0] = planes[0].mul(planes[0], 1./255);
+    //! [noisy]
 #endif
 
 
+    //! [end]
     merge(planes, I_YUV);                // now merge the results back
     cvtColor(I_YUV, I, COLOR_YCrCb2BGR);  // and produce the output RGB image
 
-
     namedWindow("image with grain", WINDOW_AUTOSIZE);   // use this to create images
 
 #ifdef DEMO_MIXED_API_USE
@@ -133,6 +143,7 @@ int main( int argc, char** argv )
 #else
     imshow("image with grain", I); // the new MATLAB style function show
 #endif
+    //! [end]
     waitKey();
 
     // Tip: No memory freeing is required!

samples/cpp/tutorial_code/core/mat_the_basic_image_container/mat_the_basic_image_container.cpp

@@ -24,62 +24,90 @@ int main(int,char**)
 {
     help();
     // create by using the constructor
+    //! [constructor]
     Mat M(2,2, CV_8UC3, Scalar(0,0,255));
     cout << "M = " << endl << " " << M << endl << endl;
+    //! [constructor]
 
     // create by using the create function()
+    //! [create]
     M.create(4,4, CV_8UC(2));
     cout << "M = "<< endl << " "  << M << endl << endl;
+    //! [create]
 
     // create multidimensional matrices
+    //! [init]
     int sz[3] = {2,2,2};
     Mat L(3,sz, CV_8UC(1), Scalar::all(0));
+    //! [init]
+
     // Cannot print via operator <<
 
     // Create using MATLAB style eye, ones or zero matrix
+    //! [matlab]
     Mat E = Mat::eye(4, 4, CV_64F);
     cout << "E = " << endl << " " << E << endl << endl;
-
     Mat O = Mat::ones(2, 2, CV_32F);
     cout << "O = " << endl << " " << O << endl << endl;
-
     Mat Z = Mat::zeros(3,3, CV_8UC1);
     cout << "Z = " << endl << " " << Z << endl << endl;
+    //! [matlab]
 
     // create a 3x3 double-precision identity matrix
+    //! [comma]
     Mat C = (Mat_<double>(3,3) << 0, -1, 0, -1, 5, -1, 0, -1, 0);
     cout << "C = " << endl << " " << C << endl << endl;
+    //! [comma]
 
+    //! [clone]
     Mat RowClone = C.row(1).clone();
     cout << "RowClone = " << endl << " " << RowClone << endl << endl;
+    //! [clone]
 
     // Fill a matrix with random values
+    //! [random]
     Mat R = Mat(3, 2, CV_8UC3);
     randu(R, Scalar::all(0), Scalar::all(255));
+    //! [random]
 
     // Demonstrate the output formating options
+    //! [out-default]
     cout << "R (default) = " << endl <<        R           << endl << endl;
+    //! [out-default]
+    //! [out-python]
     cout << "R (python)  = " << endl << format(R, Formatter::FMT_PYTHON) << endl << endl;
+    //! [out-python]
+    //! [out-numpy]
     cout << "R (numpy)   = " << endl << format(R, Formatter::FMT_NUMPY ) << endl << endl;
+    //! [out-numpy]
+    //! [out-csv]
     cout << "R (csv)     = " << endl << format(R, Formatter::FMT_CSV   ) << endl << endl;
+    //! [out-csv]
+    //! [out-c]
     cout << "R (c)       = " << endl << format(R, Formatter::FMT_C     ) << endl << endl;
+    //! [out-c]
 
+    //! [out-point2]
     Point2f P(5, 1);
     cout << "Point (2D) = " << P << endl << endl;
+    //! [out-point2]
 
+    //! [out-point3]
     Point3f P3f(2, 6, 7);
     cout << "Point (3D) = " << P3f << endl << endl;
+    //! [out-point3]
 
-
+    //! [out-vector]
     vector<float> v;
     v.push_back( (float)CV_PI);   v.push_back(2);    v.push_back(3.01f);
-
     cout << "Vector of floats via Mat = " << Mat(v) << endl << endl;
+    //! [out-vector]
 
+    //! [out-vector-points]
     vector<Point2f> vPoints(20);
     for (size_t i = 0; i < vPoints.size(); ++i)
         vPoints[i] = Point2f((float)(i * 5), (float)(i % 7));
-
     cout << "A vector of 2D Points = " << vPoints << endl << endl;
+    //! [out-vector-points]
     return 0;
 }

samples/cpp/tutorial_code/gpu/gpu-basics-similarity/gpu-basics-similarity.cpp

@@ -19,14 +19,17 @@ Scalar getMSSIM( const Mat& I1, const Mat& I2);
 double getPSNR_CUDA(const Mat& I1, const Mat& I2);  // Basic CUDA versions
 Scalar getMSSIM_CUDA( const Mat& I1, const Mat& I2);
 
+//! [psnr]
 struct BufferPSNR                                     // Optimized CUDA versions
 {   // Data allocations are very expensive on CUDA. Use a buffer to solve: allocate once reuse later.
     cuda::GpuMat gI1, gI2, gs, t1,t2;
 
     cuda::GpuMat buf;
 };
+//! [psnr]
 double getPSNR_CUDA_optimized(const Mat& I1, const Mat& I2, BufferPSNR& b);
 
+//! [ssim]
 struct BufferMSSIM                                     // Optimized CUDA versions
 {   // Data allocations are very expensive on CUDA. Use a buffer to solve: allocate once reuse later.
     cuda::GpuMat gI1, gI2, gs, t1,t2;
@@ -44,6 +47,7 @@ struct BufferMSSIM                                     // Optimized CUDA version
 
     cuda::GpuMat buf;
 };
+//! [ssim]
 Scalar getMSSIM_CUDA_optimized( const Mat& i1, const Mat& i2, BufferMSSIM& b);
 
 static void help()
@@ -165,7 +169,7 @@ int main(int, char *argv[])
     return 0;
 }
 
-
+//! [getpsnr]
 double getPSNR(const Mat& I1, const Mat& I2)
 {
     Mat s1;
@@ -186,9 +190,9 @@ double getPSNR(const Mat& I1, const Mat& I2)
         return psnr;
     }
 }
+//! [getpsnr]
 
-
-
+//! [getpsnropt]
 double getPSNR_CUDA_optimized(const Mat& I1, const Mat& I2, BufferPSNR& b)
 {
     b.gI1.upload(I1);
@@ -211,7 +215,9 @@ double getPSNR_CUDA_optimized(const Mat& I1, const Mat& I2, BufferPSNR& b)
         return psnr;
     }
 }
+//! [getpsnropt]
 
+//! [getpsnrcuda]
 double getPSNR_CUDA(const Mat& I1, const Mat& I2)
 {
     cuda::GpuMat gI1, gI2, gs, t1,t2;
@@ -237,7 +243,9 @@ double getPSNR_CUDA(const Mat& I1, const Mat& I2)
         return psnr;
     }
 }
+//! [getpsnrcuda]
 
+//! [getssim]
 Scalar getMSSIM( const Mat& i1, const Mat& i2)
 {
     const double C1 = 6.5025, C2 = 58.5225;
@@ -290,7 +298,9 @@ Scalar getMSSIM( const Mat& i1, const Mat& i2)
     Scalar mssim = mean( ssim_map ); // mssim = average of ssim map
     return mssim;
 }
+//! [getssim]
 
+//! [getssimcuda]
 Scalar getMSSIM_CUDA( const Mat& i1, const Mat& i2)
 {
     const float C1 = 6.5025f, C2 = 58.5225f;
@@ -359,7 +369,9 @@ Scalar getMSSIM_CUDA( const Mat& i1, const Mat& i2)
     }
     return mssim;
 }
+//! [getssimcuda]
 
+//! [getssimopt]
 Scalar getMSSIM_CUDA_optimized( const Mat& i1, const Mat& i2, BufferMSSIM& b)
 {
     const float C1 = 6.5025f, C2 = 58.5225f;
@@ -430,3 +442,4 @@ Scalar getMSSIM_CUDA_optimized( const Mat& i1, const Mat& i2, BufferMSSIM& b)
     }
     return mssim;
 }
+//! [getssimopt]

samples/cpp/tutorial_code/introduction/display_image/display_image.cpp

@@ -1,23 +1,35 @@
+//! [includes]
 #include <opencv2/core/core.hpp>
 #include <opencv2/imgcodecs.hpp>
 #include <opencv2/highgui/highgui.hpp>
 
 #include <iostream>
 #include <string>
+//! [includes]
 
+//! [namespace]
 using namespace cv;
+//! [namespace]
+
 using namespace std;
 
 int main( int argc, char** argv )
 {
+    //! [load]
     string imageName("../data/HappyFish.jpg"); // by default
     if( argc > 1)
     {
         imageName = argv[1];
     }
+    //! [load]
 
+    //! [mat]
     Mat image;
+    //! [mat]
+
+    //! [imread]
     image = imread(imageName.c_str(), IMREAD_COLOR); // Read the file
+    //! [imread]
 
     if( image.empty() )                      // Check for invalid input
     {
@@ -25,9 +37,16 @@ int main( int argc, char** argv )
         return -1;
     }
 
+    //! [window]
     namedWindow( "Display window", WINDOW_AUTOSIZE ); // Create a window for display.
-    imshow( "Display window", image );                // Show our image inside it.
+    //! [window]
 
+    //! [imshow]
+    imshow( "Display window", image );                // Show our image inside it.
+    //! [imshow]
+
+    //! [wait]
     waitKey(0); // Wait for a keystroke in the window
+    //! [wait]
     return 0;
 }