sync with upstream

2 files changed, 119 insertions, 0 deletions

diff --git a/xbmc/addons/kodi-addon-dev-kit/doxygen/General/DoxygenOnAddon.dox b/xbmc/addons/kodi-addon-dev-kit/doxygen/General/DoxygenOnAddon.dox
new file mode 100644
index 0000000..7502e5e
--- /dev/null
+++ b/xbmc/addons/kodi-addon-dev-kit/doxygen/General/DoxygenOnAddon.dox
@@ -0,0 +1,90 @@
+/*!
+
+@page Doxygen_On_Addon Doxygen on Kodi's Add-On headers
+
+### This page is for notes on using Doxygen to document the Kodi's Add-On headers source code.
+
+[Doxygen](http://www.stack.nl/~dimitri/doxygen/index.html), is a documentation
+system for C++, C, Java, and some other weird languages. It can generate html
+docs documenting a projects source code, by either extracting special tags from
+the source code (put there by people wanting to make use of doxygen), or doxygen
+attempts to build documentation from existing source.
+
+Doxygen seems to be installed on the NMR systems, type:
+~~~~~~~~~~~~~
+doxygen --version
+~~~~~~~~~~~~~
+
+
+_ _ _
+
+Start doxygen documentation for add-ons always with `///` and on Kodi itself with `/*!`, this makes it more easy to see for which place the documentation is.
+
+<b>Here an example on add-on about function coding style:</b>
+
+\verbatim
+#ifdef DOXYGEN_SHOULD_USE_THIS
+  ///
+  /// \ingroup python_xbmcgui_window
+  /// @brief Sets the resolution
+  ///
+  /// That the coordinates of all controls are defined in.  Allows Kodi
+  /// to scale control positions and width/heights to whatever resolution
+  /// Kodi is currently using.
+  ///
+  /// @param[in] res                Coordinate resolution to set
+  ///  Resolution is one of the following:
+  ///  | value | Resolution                |
+  ///  |:-----:|:--------------------------|
+  ///  |   0   | 1080i      (1920x1080)
+  ///  |   1   | 720p       (1280x720)
+  ///  |   2   | 480p 4:3   (720x480)
+  ///  |   3   | 480p 16:9  (720x480)
+  ///  |   4   | NTSC 4:3   (720x480)
+  ///  |   5   | NTSC 16:9  (720x480)
+  ///  |   6   | PAL 4:3    (720x576)
+  ///  |   7   | PAL 16:9   (720x576)
+  ///  |   8   | PAL60 4:3  (720x480)
+  ///  |   9   | PAL60 16:9 (720x480)
+  /// @return                       Nothing only added as example here :)
+  /// @param[out] nothingExample    Example here, if on value pointer data becomes
+  ///                               returned.
+  /// @throws TypeError             If supplied argument is not of List type, or a
+  ///                               control is not of Control type
+  /// @throws ReferenceError        If control is already used in another window
+  /// @throws RuntimeError          Should not happen :-)
+  ///
+  ///
+  ///--------------------------------------------------------------------------
+  ///
+  /// **Example:**
+  /// ~~~~~~~~~~~~~{.py}
+  /// ..
+  /// win = xbmcgui.Window(xbmcgui.getCurrentWindowId())
+  /// win.setCoordinateResolution(0)
+  /// ..
+  /// ~~~~~~~~~~~~~
+  ///
+  setCoordinateResolution(...);
+#else
+  SWIGHIDDENVIRTUAL bool setCoordinateResolution(long res, int &nothingExample);
+#endif
+\endverbatim
+- \verbatim /// \ingroup\endverbatim - Define the group where the documentation part comes in.
+- \verbatim /// @brief\endverbatim - Add a small text of part there.
+- \verbatim /// TEXT_FIELD\endverbatim - Add a bigger text there if needed.
+- \verbatim /// @param[in] VALUE_NAME                 VALUE_TEXT\endverbatim - To set input parameter defined by name and add a description. There the example also add a small table which is useful to describe values.
+- \verbatim /// @param[out] VALUE_NAME                VALUE_TEXT\endverbatim - To set output parameter defined by name and add a description.
+- \verbatim /// @return                               VALUE_TEXT\endverbatim - To add a description of return value.
+- \verbatim /// @throws ERROR_TYPE                    ERROR_TEXT\endverbatim - If also exception becomes handled, can you use this for description.
+- \verbatim /// TEXT_FIELD\endverbatim - Add a much bigger text there if needed.
+- \verbatim /// ------------------\endverbatim - Use this to define a field line, e.g. if you add example add this always before, further must you make two empty lines before to prevent add of them on string before!
+- \verbatim /// ~~~~~~~~~~~~~ \endverbatim - Here can you define a code example which must start and end with the defination string, also can you define the code style with e.g. <b>{.py}</b> for Python or <b>{.cpp}</b> for CPP code on the first line of them.
+
+@note Start all `VALUE_TEXT` at same character to hold a clean code on <c>*.cpp</c> or <c>*.h</c> files.\n\n
+      The `#ifdef DOXYGEN_SHOULD_USE_THIS` on example above can be becomes used
+      if for Doxygen another function is needed to describe.
+
+If you want to prevent a part from doxygen can you define <b>`#ifndef DOXYGEN_SHOULD_SKIP_THIS`</b>
+or <b>`#ifdef DOXYGEN_SHOULD_USE_THIS`</b> on the related code.
+*/
diff --git a/xbmc/addons/kodi-addon-dev-kit/doxygen/General/General.dox b/xbmc/addons/kodi-addon-dev-kit/doxygen/General/General.dox
new file mode 100644
index 0000000..ef7ccf0
--- /dev/null
+++ b/xbmc/addons/kodi-addon-dev-kit/doxygen/General/General.dox
@@ -0,0 +1,29 @@
+/*!
+
+\page general General
+\brief \doc_header{ General descriptions }
+
+The used code guidelines from Kodi
+@note Is not direct needed on C++ add-ons but makes it more easy for reviews and
+changes from the others.
+
+\subpage code_guidelines
+
+--------------------------------------------------------------------------------
+
+Guideline for Kodi's developers to create documentation
+
+\subpage Doxygen_On_Addon
+
+*/
+
+---------------------------------------------------------------------------------
+
+@subpage revisions "Revisions against older versions"
+*/
+
+/*!
+\page revisions Revisions
+
+\subpage python_revisions
+*/
\ No newline at end of file