From f44ecaa4f27e7538ddcad66d40e543bffa2d2d86 Mon Sep 17 00:00:00 2001 From: manuel Date: Sun, 4 Jun 2017 16:57:49 +0200 Subject: sync with upstream --- .../doxygen/General/DoxygenOnAddon.dox | 90 ++++++++++++++++++++++ .../kodi-addon-dev-kit/doxygen/General/General.dox | 29 +++++++ 2 files changed, 119 insertions(+) create mode 100644 xbmc/addons/kodi-addon-dev-kit/doxygen/General/DoxygenOnAddon.dox create mode 100644 xbmc/addons/kodi-addon-dev-kit/doxygen/General/General.dox (limited to 'xbmc/addons/kodi-addon-dev-kit/doxygen/General') 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. + +Here an example on add-on about function coding style: + +\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 ¬hingExample); +#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. {.py} for Python or {.cpp} for CPP code on the first line of them. + +@note Start all `VALUE_TEXT` at same character to hold a clean code on *.cpp or *.h 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 `#ifndef DOXYGEN_SHOULD_SKIP_THIS` +or `#ifdef DOXYGEN_SHOULD_USE_THIS` 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 -- cgit v1.2.3