Merge pull request opencv#9773 from shoeffner:feature/doxygen-tag-file

mshabunin · mshabunin · commit 56fe2dc1ed9a · 2017-10-06T10:44:58.000Z
diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
@@ -255,7 +255,7 @@ PREDEFINED             = __cplusplus=1 \
 EXPAND_AS_DEFINED      =
 SKIP_FUNCTION_MACROS   = YES
 TAGFILES               =
-GENERATE_TAGFILE       =
+GENERATE_TAGFILE       = @CMAKE_DOXYGEN_OUTPUT_PATH@/html/opencv.tag
 ALLEXTERNALS           = NO
 EXTERNAL_GROUPS        = YES
 EXTERNAL_PAGES         = YES
diff --git a/doc/tutorials/introduction/cross_referencing/tutorial_cross_referencing.markdown b/doc/tutorials/introduction/cross_referencing/tutorial_cross_referencing.markdown
@@ -0,0 +1,61 @@
+Cross referencing OpenCV from other Doxygen projects {#tutorial_cross_referencing}
+====================================================
+
+Cross referencing OpenCV
+------------------------
+
+[Doxygen](https://www.stack.nl/~dimitri/doxygen/) is a tool to generate
+documentations like the OpenCV documentation you are reading right now.
+It is used by a variety of software projects and if you happen to use it
+to generate your own documentation, and you are using OpenCV inside your
+project, this short tutorial is for you.
+
+Imagine this warning inside your documentation code:
+
+@code
+/**
+ * @warning This functions returns a cv::Mat.
+ */
+@endcode
+
+Inside your generated documentation this warning will look roughly like this:
+
+@warning This functions returns a %cv::Mat.
+
+While inside the OpenCV documentation the `%cv::Mat` is rendered as a link:
+
+@warning This functions returns a cv::Mat.
+
+To generate links to the OpenCV documentation inside your project, you only
+have to perform two small steps. First download the file
+[opencv.tag](opencv.tag) (right-click and choose "save as...") and place it
+somewhere in your project directory, for example as
+`docs/doxygen-tags/opencv.tag`.
+
+Open your Doxyfile using your favorite text editor and search for the key
+`TAGFILES`. Change it as follows:
+
+@code
+TAGFILES = ./docs/doxygen-tags/opencv.tag=http://docs.opencv.org/3.3.0
+@endcode
+
+If you had other definitions already, you can append the line using a `\`:
+
+@code
+TAGFILES = ./docs/doxygen-tags/libstdc++.tag=https://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen \
+           ./docs/doxygen-tags/opencv.tag=http://docs.opencv.org/3.3.0
+@endcode
+
+Doxygen can now use the information from the tag file to link to the OpenCV
+documentation. Rebuild your documentation right now!
+
+@note To allow others to also use a *.tag file to link to your documentation,
+set `GENERATE_TAGFILE = html/your_project.tag`. Your documentation will now
+contain a `your_project.tag` file in its root directory.
+
+
+References
+----------
+
+- [Doxygen: Linking to external documentation](https://www.stack.nl/~dimitri/doxygen/manual/external.html)
+- [opencv.tag](opencv.tag)
diff --git a/doc/tutorials/introduction/table_of_content_introduction.markdown b/doc/tutorials/introduction/table_of_content_introduction.markdown
@@ -171,3 +171,11 @@ Additionally you can find very basic sample source code to introduce you to the
     _Author:_ Maksim Shabunin
 
     This document describes some aspects of 2.4 -> 3.0 transition process.
+
+-   @subpage tutorial_cross_referencing
+
+    _Compatibility:_ \> OpenCV 3.3.0
+
+    _Author:_ Sebastian Höffner
+
+    This document outlines how to create cross references to the OpenCV documentation from other Doxygen projects.
