diff --git a/CMakeLists.txt b/CMakeLists.txt
index 47a1837799570f7427e69a204283d981a7609f82..574141293409522be8fc97b393f009d623c744fa 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -1131,7 +1131,7 @@ generate_pkgconfig_file()
##################
set(CPACK_SOURCE_GENERATOR "TGZ")
set(CPACK_PACKAGE_NAME "chameleon")
-set(CPACK_PACKAGE_DESCRIPTION_FILE ${CMAKE_CURRENT_SOURCE_DIR}/README.md)
+set(CPACK_PACKAGE_DESCRIPTION_FILE ${CMAKE_CURRENT_SOURCE_DIR}/README.org)
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "Chameleon is a C library providing parallel algorithms to perform BLAS/LAPACK "
" operations exploiting fully modern architectures.")
set(CHAMELEON_VERSION_PATCH ${CHAMELEON_VERSION_MICRO})
@@ -1140,7 +1140,7 @@ set(CPACK_PACKAGE_FILE_NAME "${CPACK_PACKAGE_NAME}-${CPACK_PACKAGE_VERSION}")
set(CPACK_SOURCE_PACKAGE_FILE_NAME "${CPACK_PACKAGE_NAME}-${CPACK_PACKAGE_VERSION}")
set(CPACK_PACKAGE_VENDOR "Inria")
set(CPACK_PACKAGE_CONTACT "morse-devel@lists.gforge.inria.fr")
-set(CPACK_RESOURCE_FILE_README ${CMAKE_CURRENT_SOURCE_DIR}/README.md)
+set(CPACK_RESOURCE_FILE_README ${CMAKE_CURRENT_SOURCE_DIR}/README.org)
set(CPACK_RESOURCE_FILE_LICENSE ${CMAKE_CURRENT_SOURCE_DIR}/LICENCE.txt)
set(CPACK_SOURCE_IGNORE_FILES "plasma-conversion;build;.cproject;.settings;.dir-locals.el;.project;.pydevproject;.svn;.git;.gitmodules;.gitlab-ci.yml")
include(CPack)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
deleted file mode 100644
index b2fd3dba263bc1ec30415efd75ce9bd421496f14..0000000000000000000000000000000000000000
--- a/CONTRIBUTING.md
+++ /dev/null
@@ -1,60 +0,0 @@
-# To contribute to the project, you need to do it through pull/merge request
-
-First you need to fork the repository into your own account. You can do that simply by clicking the fork button on the gitlab interface.
-
-https://gitlab.inria.fr/solverstack/chameleon/forks/new
-
-Then, clone the repository on your laptop:
-```
-#!shell
-git clone git@gitlab.inria.fr:username/forkname.git
-```
-
-Once this is done, you can setup the chameleon repository as the upstream of your clone to simplify the update of your fork repository.
-```
-#!shell
-git remote add upstream git@gitlab.inria.fr:solverstack/chameleon.git
-```
-
-To update your fork with the upstream chameleon's state:
-```
-#!shell
-git pull upstream master
-git push -u origin master
-```
-
-Now, you have your repository configured, and you want to create a new pull request. The first step is to create a branch from the HEAD of the your fork repository.
-```
-#!shell
-git branch your_branch_name
-git checkout your_branch_name
-```
-
-Apply your modifications in your branch. Then, you need to push this branch on your online repository
-```
-#!shell
-git push -f origin your_branch_name
-```
-
-or without -f, if the branch already exists online, and you just want to update it.
-
-Once your branch is online, on the gitlab interface, go to the branches webpage, select the branch you want to push as a merge request, and push the button !!!
-
-***Be careful to check the 'close after merge' check box, and to push to the solverstack/chameleon repository*** By default the checkbox is not checked, and the default repository is your fork.
-
-
-# To review locally a private pull request submitted by someone else
-
-Get the patch from the pull request (Need to update that !!!! Coming from bitbucket)
-```
-#!shell
-curl https://bitbucket.org/api/2.0/repositories/icldistcomp/parsec/pullrequests/#PR/patch > pr#PR.patch
-```
-
-Than apply the patch on your local copy
-
-```
-#!shell
-
-git apply pr#PR.patch
-```
diff --git a/CONTRIBUTING.org b/CONTRIBUTING.org
new file mode 100644
index 0000000000000000000000000000000000000000..705c6d1ff83f0b34e82aa59d826343fe979cc8d5
--- /dev/null
+++ b/CONTRIBUTING.org
@@ -0,0 +1,88 @@
+* To contribute to the project, you need to do it through merge request
+
+ First you need to fork the repository into your own account. You can
+ do that simply by clicking the fork button on the gitlab interface.
+
+ https://gitlab.inria.fr/solverstack/chameleon/forks/new
+
+ Then, clone the repository on your laptop:
+ #+begin_src sh
+ git clone git@gitlab.inria.fr:username/forkname.git
+ #+end_src
+
+ Once this is done, you can setup the chameleon repository as the
+ upstream of your clone to simplify the update of your fork
+ repository.
+ #+begin_src sh
+ git remote add upstream git@gitlab.inria.fr:solverstack/chameleon.git
+ #+end_src
+
+ To update your fork with the upstream chameleon's state:
+ #+begin_src sh
+ git pull upstream master
+ git push -u origin master
+ #+end_src
+
+ Now, you have your repository configured, and you want to create a
+ new pull request. The first step is to create a branch from the HEAD
+ of the your fork repository.
+
+ #+begin_src sh
+ git branch your_branch_name
+ git checkout your_branch_name
+ #+end_src
+
+ Apply your modifications in your branch. Then, you need to push this
+ branch on your online repository
+ #+begin_src sh
+ git push -f origin your_branch_name
+ #+end_src
+ or without -f, if the branch already exists online, and you just
+ want to update it.
+
+ Once your branch is online, on the gitlab interface, go to the
+ branches webpage, select the branch you want to push as a merge
+ request, and push the button !!!
+
+ *Be careful to check the 'close after merge' check box, and to push
+ to the solverstack/chameleon repository*. By default the checkbox
+ may not be checked, and the default repository is your fork.
+
+ If the pull request is made to fix an issue, please name the branch
+ "issueXX" so it is automatically linked to the issue. In addition,
+ please add "fix issue #xx" in the comment of the pull request to
+ automatically close the issue when the PR is merged.
+
+** Rebase on top of 'master'
+
+ In some cases your "feature" branch you want to merge into "master"
+ has a long life span so that your branch and the master branch
+ could make some conflicts. To avoid having to handle the possible
+ conflicts at *merge request* time, please rebase your "feature" on
+ top of "master" before pushing the button *merge request*.
+
+ To do that, just go at the HEAD of your "feature" branch and rebase
+ #+begin_src sh
+ git checkout feature
+ git rebase master
+ #+end_src
+
+ Then force to push on your origin
+ #+begin_src sh
+ git push --force origin feature
+ #+end_src
+
+ Then push the button *merge request*.
+
+* To review locally a private pull request submitted by someone else
+
+ Get the patch from the pull request (Need to update that !!!!
+ Coming from bitbucket)
+ #+begin_src sh
+ curl https://bitbucket.org/api/2.0/repositories/icldistcomp/parsec/pullrequests/#PR/patch > pr#PR.patch
+ #+end_src
+
+ Then apply the patch on your local copy
+ #+begin_src sh
+ git apply pr#PR.patch
+ #+end_src
diff --git a/README.md b/README.md
deleted file mode 100644
index e6fa51cfbf2a0912336b1c3d6e0950979460b4ac..0000000000000000000000000000000000000000
--- a/README.md
+++ /dev/null
@@ -1,120 +0,0 @@
-Chameleon: A dense linear algebra software for heterogeneous architectures
-====================
-
-Chameleon is a C library providing parallel algorithms to perform
-BLAS/LAPACK operations exploiting fully modern architectures.
-
-Chameleon dense linear algebra software relies on sequential
-task-based algorithms where sub-tasks of the overall algorithms are
-submitted to a Runtime system. Such a system is a layer between the
-application and the hardware which handles the scheduling and the
-effective execution of tasks on the processing units. A Runtime system
-such as [StarPU](http://starpu.gforge.inria.fr/) is able to manage
-automatically data transfers between not shared memory area
-(CPUs-GPUs, distributed nodes).
-
-This kind of implementation paradigm allows to design high performing
-linear algebra algorithms on very different type of architecture:
-laptop, many-core nodes, CPUs-GPUs, multiple nodes. For example,
-Chameleon is able to perform a Cholesky factorization
-(double-precision) at 80 TFlop/s on a dense matrix of order 400 000
-(i.e. 4 min). Chameleon is a sub-project of
-[MORSE](http://icl.cs.utk.edu/morse/) specifically dedicated to dense
-linear algebra.
-
-Get Chameleon
----------------------
-
-To use last development states of Chameleon, please clone the master
-branch. Note that Chameleon contains a `git submodule` **morse_cmake**.
-To get sources please use these commands:
-
- # if git version >= 1.9
- git clone --recursive git@gitlab.inria.fr:solverstack/chameleon.git
- cd chameleon
- # else
- git clone git@gitlab.inria.fr:solverstack/chameleon.git
- cd chameleon
- git submodule init
- git submodule update
-
-Last releases of Chameleon are hosted on the
-[gforge.inria.fr](https://gforge.inria.fr/frs/?group_id=2884) for now.
-Future releases will be available on this gitlab project.
-
-Documentation
----------------------
-
-There is no up-to-date documentation of Chameleon. We would like to
-provide a doxygen documentation hosted on
-[gitlab](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/) in
-the future.
-
-The documentation of Chameleon's last release is available here:
-[chameleon-0.9.1
-documentation](http://morse.gforge.inria.fr/chameleon/0.9.1/chameleon_users_guide-0.9.1.html)
-
-Installation
----------------------
-
-### Build and install with CMake
-
-Chameleon can be built using [CMake](https://cmake.org/). This
-installation requires to have some library dependencies already
-installed on the system.
-
-Please refer to the
-[chameleon-0.9.1](http://morse.gforge.inria.fr/chameleon/0.9.1/chameleon_users_guide-0.9.1.html#Installing-CHAMELEON)
-to get configuration information.
-
-### Distribution of Chameleon
-To get support to install a full distribution (Chameleon +
-dependencies) we encourage users to use the morse branch of
-**Spack**.
-
-Please read these documentations:
-
-* [Spack Morse](http://morse.gforge.inria.fr/spack/spack.html).
-* [Section Chameleon](http://morse.gforge.inria.fr/spack/spack.html#sec-2-1).
-
-Get involved!
----------------------
-
-### Mailing list
-
-TODO
-
-### Contributions
-
-https://gitlab.inria.fr/solverstack/chameleon/blob/master/CONTRIBUTING.md
-
-### Authors
-
-First, since the Chameleon library started as an extension of the PLASMA library
-to support multiple runtime systems, all developpers of the PLASMA library are
-developpers of the Chameleon library.
-
-The following people contributed to the development of Chameleon:
- * Emmanuel Agullo, PI
- * Olivier Aumage
- * Cedric castagnede
- * Terry Cojean
- * Mathieu Faverge, PI
- * Nathalie Furmento
- * Reazul Hoque, PaRSEC support
- * Gregoire Pichon, Two-sided algorithms
- * Florent Pruvost, PI, CMake and Spack
- * Marc Sergent
- * Guillaume Sylvand
- * Samuel Thibault, StarPU support
- * Omar Zenati
-
-If we forgot your name, please let us know that we can fix that mistake.
-
-### Citing Chameleon
-
-TODO
-
-### Licence
-
-https://gitlab.inria.fr/solverstack/chameleon/blob/master/LICENCE.txt
diff --git a/README.org b/README.org
new file mode 100644
index 0000000000000000000000000000000000000000..b9f1dacaa43e3e8e08a9c3291de92bcb3b5ee527
--- /dev/null
+++ b/README.org
@@ -0,0 +1,154 @@
+#+TITLE: Chameleon: A dense linear algebra software for heterogeneous architectures
+#+LANGUAGE: en
+#+OPTIONS: H:3 num:t \n:nil @:t ::t |:t _:nil ^:nil -:t f:t *:t <:t
+#+OPTIONS: TeX:t LaTeX:t skip:nil d:nil pri:nil tags:not-in-toc html-style:nil
+
+Chameleon is a C library providing parallel algorithms to perform
+BLAS/LAPACK operations exploiting fully modern architectures.
+
+Chameleon dense linear algebra software relies on sequential
+task-based algorithms where sub-tasks of the overall algorithms are
+submitted to a Runtime system. Such a system is a layer between the
+application and the hardware which handles the scheduling and the
+effective execution of tasks on the processing units. A Runtime system
+such as [[http://starpu.gforge.inria.fr/][StarPU]] is able to manage automatically data transfers between
+not shared memory area (CPUs-GPUs, distributed nodes).
+
+This kind of implementation paradigm allows to design high performing
+linear algebra algorithms on very different type of architecture:
+laptop, many-core nodes, CPUs-GPUs, multiple nodes. For example,
+Chameleon is able to perform a Cholesky factorization
+(double-precision) at 80 TFlop/s on a dense matrix of order 400 000
+(i.e. 4 min). Chameleon is a sub-project of [[http://icl.cs.utk.edu/morse/][MORSE]] specifically
+dedicated to dense linear algebra.
+
+* Get Chameleon
+
+ To use last development states of Chameleon, please clone the master
+ branch. Note that Chameleon contains a ~git submodule~ *morse_cmake*.
+ To get sources please use these commands:
+
+ #+begin_src sh
+ # if git version >= 1.9
+ git clone --recursive git@gitlab.inria.fr:solverstack/chameleon.git
+ cd chameleon
+ # else
+ git clone git@gitlab.inria.fr:solverstack/chameleon.git
+ cd chameleon
+ git submodule init
+ git submodule update
+ #+end_src
+
+ Last releases of Chameleon are hosted on the [[https://gforge.inria.fr/frs/?group_id=2884][gforge.inria.fr]] for
+ now. Future releases will be available on this gitlab project.
+
+* Documentation
+
+ There is no up-to-date documentation of Chameleon. We would like to
+ provide a doxygen documentation hosted on [[https://about.gitlab.com/2016/04/07/gitlab-pages-setup/][gitlab]] in the
+ future. Please refer to the section 2.1 of [[file:READMEDEV.org][READMEDEV]] to get
+ information about the documentation generation.
+
+ The documentation of Chameleon's last release is available here:
+ [[http://morse.gforge.inria.fr/chameleon/0.9.1/chameleon_users_guide-0.9.1.html][chameleon-0.9.1 documentation]].
+
+** For developers
+
+ [[file:READMEDEV.org][READMEDEV]]
+
+* Installation
+
+** Distribution of Chameleon
+
+ To get support to install a full distribution (Chameleon +
+ dependencies) we encourage users to use the morse branch of *Spack*.
+
+ Please read these documentations:
+
+ * [[http://morse.gforge.inria.fr/spack/spack.html][Spack Morse]]
+ * [[http://morse.gforge.inria.fr/spack/spack.html#sec-2-1][Section Chameleon]]
+
+*** Usage example for a simple distribution of Chameleon
+
+ #+begin_src sh
+ git clone https://github.com/solverstack/spack.git
+ . ./spack/share/spack/setup-env.sh
+ spack install -v chameleon
+ # chameleon is installed here:
+ `spack location -i chameleon`
+ #+end_src
+
+** Build and install with CMake
+
+ Chameleon can be built using [[https://cmake.org/][CMake]]. This installation requires to
+ have some library dependencies already installed on the system.
+
+ Please refer to [[http://morse.gforge.inria.fr/chameleon/0.9.1/chameleon_users_guide-0.9.1.html#Installing-CHAMELEON][chameleon-0.9.1]] to get configuration information.
+
+* Get involved!
+
+** Mailing list
+
+ To contact the developers send an email to
+ [[mailto:morse-devel@lists.gforge.inria.fr][morse-devel@lists.gforge.inria.fr]]
+
+** Contributions
+
+ [[file:CONTRIBUTING.org][CONTRIBUTING]]
+
+* Authors
+
+ First, since the Chameleon library started as an extension of the
+ PLASMA library to support multiple runtime systems, all developpers
+ of the PLASMA library are developpers of the Chameleon library.
+
+ The following people contributed to the development of Chameleon:
+ * Emmanuel Agullo, PI
+ * Olivier Aumage
+ * Cedric castagnede
+ * Terry Cojean
+ * Mathieu Faverge, PI
+ * Nathalie Furmento
+ * Reazul Hoque, PaRSEC support
+ * Gregoire Pichon, Two-sided algorithms
+ * Florent Pruvost, PI, CMake and Spack
+ * Marc Sergent
+ * Guillaume Sylvand
+ * Samuel Thibault, StarPU support
+ * Omar Zenati
+
+ If we forgot your name, please let us know that we can fix that mistake.
+
+* Citing Chameleon
+
+Feel free to use the following publications to reference Chameleon:
+
+ * Original paper that initiated Chameleon and the principles:
+ - Agullo, Emmanuel and Augonnet, Cédric and Dongarra, Jack and
+ Ltaief, Hatem and Namyst, Raymond and Thibault, Samuel and Tomov,
+ Stanimire, *Faster, Cheaper, Better -- a Hybridization Methodology
+ to Develop Linear Algebra Software for GPUs*, /GPU Computing Gems/,
+ [[https://hal.inria.fr/inria-00547847][First Online: 17 December 2010]].
+ * Design of the QR algorithms:
+ - Agullo, Emmanuel and Augonnet, Cédric and Dongarra, Jack and
+ Faverge, Mathieu and Ltaief, Hatem and Thibault, Samuel an
+ Tomov, Stanimire, *QR Factorization on a Multicore Node Enhanced
+ with Multiple GPU Accelerators*, /25th IEEE International Parallel
+ & Distributed Processing Symposium/, [[https://hal.inria.fr/inria-00547614][First Online: 16 December
+ 2010]].
+ * Design of the LU algorithms:
+ - Agullo, Emmanuel and Augonnet, Cédric and Dongarra, Jack and
+ Faverge, Mathieu and Langou, Julien and Ltaief, Hatem and Tomov,
+ Stanimire, *LU Factorization for Accelerator-based Systems*,
+ /9th ACS/IEEE International Conference on Computer Systems and
+ Applications (AICCSA 11)/, [[https://hal.inria.fr/hal-00654193][First Online: 21 December 2011]].
+ * Regarding distributed memory:
+ - Agullo, Emmanuel and Aumage, Olivier and Faverge, Mathieu and
+ Furmento, Nathalie and Pruvost, Florent and Sergent, Marc and
+ Thibault, Samuel, *Achieving High Performance on Supercomputers
+ with a Sequential Task-based Programming Model*, /Research Report/,
+ [[https://hal.inria.fr/hal-01332774][First Online: 16 June 2016]].
+
+* Licence
+
+ [[file:LICENCE.txt][LICENCE]]
diff --git a/READMEDEV.org b/READMEDEV.org
new file mode 100644
index 0000000000000000000000000000000000000000..cdaefe4fe096473bff0a9c6ccea9004e9ac943d8
--- /dev/null
+++ b/READMEDEV.org
@@ -0,0 +1,103 @@
+#+TITLE: README for developers
+#+LANGUAGE: en
+#+OPTIONS: H:3 num:t \n:nil @:t ::t |:t _:nil ^:nil -:t f:t *:t <:t
+#+OPTIONS: TeX:t LaTeX:t skip:nil d:nil pri:nil tags:not-in-toc html-style:nil
+
+This page is dedicated to rules and conventions that Chameleon's
+developers must follow and that should be read by contributors.
+
+* Gitlab flow: how to contribute to Chameleon
+
+ Please read and follow guidelines given in the [[file:CONTRIBUTING.org][CONTRIBUTING file]].
+
+** Update submodules
+
+ Chameleon git project depends on a "submodule" git, located in
+ cmake_modules/morse_cmake and hosted here
+ https://gitlab.inria.fr/solverstack/morse_cmake.
+
+ To update this submodule to the last development state, follow
+ these steps:
+
+ #+begin_src sh
+ git submodule update --remote cmake_modules/morse_cmake
+ git commit cmake_modules/morse_cmake -m "update morse_cmake submodule"
+ git push --recurse-submodules=check
+ #+end_src
+
+* Documentation
+ <<sec:doc>>
+** Generate the documentation
+
+*** Prerequisites
+
+ To generate the documentation you need to have [[http://www.stack.nl/~dimitri/doxygen/][Doxygen]] and
+ [[https://www.gnu.org/software/texinfo/][Texinfo]] installed on your system.
+
+ For example, on Debian systems:
+ #+begin_src sh
+ sudo apt install doxygen texinfo
+ #+end_src
+
+*** configure + make documentation
+
+ Enter into the Chameleon's source root directory and configure
+ with *CHAMELEON_ENABLE_DOCS=ON*, then generate the documentation
+ with ~make docs~
+
+ #+begin_src sh
+ cd chameleon
+ mkdir build && cd build
+ cmake .. -DCHAMELEON_ENABLE_DOCS=ON
+ make docs
+ #+end_src
+
+** Rules about source code documentation
+
+ Please refer to this file for the documentation guidelines [[file:docs/doxygen/README.org][README]].
+
+* Naming and writting conventions
+
+ Chameleon library started as an extension of the PLASMA library so
+ that code naming and writting conventions should follow [[https://bitbucket.org/icl/plasma][PLASMA]] ones.
+
+* Packaging
+
+ A Chameleon's release is a source package, of the form
+ chameleon-major.minor.patch.tar.gz, which:
+ 1) has been properly tested,
+ 2) contains a generated documentation corresponding to the released version,
+ 3) has an up-to-date ChangeLog file,
+ 4) is published on internet.
+
+** Test Chameleon before packaging
+
+ TODO - Write the way we could systematically test Chameleon before
+ packaging, for example writting a script (generated from this
+ org-mode file) to be used on PlaFRIM plus some specific ctest
+ tests.
+
+** Source tarball generation
+
+ This step requires to generate the [[sec:doc][documentation]].
+
+ #+begin_src sh
+ export CHAMELEON_ROOT=/path/to/chameleon/sources/to/be/released
+ cmake $CHAMELEON_ROOT -DCHAMELEON_ENABLE_DOCS=ON
+ make docs && cp docs/texinfo/users_guide.pdf $CHAMELEON_ROOT && make package_source
+ #+end_src
+
+ A tarball chameleon-major.minor.patch.tar.gz should be generated
+ and contains the users_guide documentation.
+
+** Publish the release on internet
+
+ A git tag must be first created, for example
+ #+begin_src sh
+ git tag -a v1.0.0 -m 'Version 1.0.0'
+ git push --tags
+ #+end_src
+
+ Then in the Chameleon *Tags* tab,
+ https://gitlab.inria.fr/solverstack/chameleon/tags, edit the
+ release notes and attach the tarball previously generated.
diff --git a/docs/doxygen/README.org b/docs/doxygen/README.org
new file mode 100644
index 0000000000000000000000000000000000000000..b9d930b754d3cc649ddc6f16f5050045c4f4aebf
--- /dev/null
+++ b/docs/doxygen/README.org
@@ -0,0 +1,178 @@
+#+TITLE: Doxygen Documentation
+
+Document all functions prototypes, modules, macros, structures and
+variables. Doxygen is not very flexible: read this documentation and
+follow the guidelines. Remember to generate the documentation, and
+check that it appears as expected.
+
+The file ~xxxx.c~ has examples of all features used in the
+documentation.
+
+* Functions Prototype Documentation
+ To document a function, use the following format:
+
+ #+begin_src c
+ /**
+ *******************************************************************************
+ *
+ * @ingroup name_of_parent_module
+ *
+ * @brief Single line explanation of the function
+ *
+ * Multiple lines explaining the detailed function behavior
+ * exceptions, preconditions, algorithm, etc.
+ *
+ *******************************************************************************
+ *
+ * @param[inout] name_of_parameter
+ * Explanation of the parameter
+ *
+ * @param[in] name_of_parameter
+ * Explanation of the parameter
+ *
+ *******************************************************************************
+ *
+ * @return Explain what is returned by the function
+ *
+ * or
+ *
+ * @retval value1 explanation of the returned value and in which case it is returned
+ * @retval value2 ...
+ *
+ *******************************************************************************/
+ int
+ function(int param1, int *param2)
+ {
+ }
+ #+end_src
+
+ ~[in]~ *must* be attached to ~@param~, and *it must* be /lower
+ case/. Otherwise, Doxygen thinks the name of the parameter is ~[IN]~.
+
+ Blank lines are /important/: there must be a blank line between ~@brief~
+ and the ~details~ section.
+
+* Structures documentation
+
+ Use the following format:
+
+ #+begin_src c
+ /**
+ * @ingroup name_of_parent_module
+
+ * @brief Single line explanation of the structure
+ *
+ * General description of the structure
+ */
+ struct name_s {
+ type1 field1; /**< What is stored in this field */
+ type2 field2; /**< What is stored in this field */
+ };
+ #+end_src
+
+ It is important to use the ~/**<~ marker, or the description of the
+ field is not imported in an array representation of the data
+ structure.
+
+* Macros Documentation
+
+ Use the following format:
+
+ #+begin_src c
+ /**
+ * @ingroup name_of_parent_module
+ *
+ * @brief Single line explanation of the macro
+ *
+ * General description of the macro if needed
+ */
+ #define macro
+ #+end_src
+
+ Without the ~@brief~, the documentation does not appear just under the
+ macro definition. All macro definitions are output directly in the
+ generated documentation.
+
+* Variable Documentation
+
+ Use the following format:
+
+ #+begin_src c
+ /**
+ * @ingroup name_of_parent_module
+ *
+ * @brief Single line explanation of the variable
+ *
+ * General description of the variable if needed
+ */
+ int var;
+ #+end_src
+
+ Without the ~@brief~, the documentation does not appear just under the
+ variable definition.
+
+* Modules Documentation
+
+ General documentation on how the functions of a same module are used
+ together belong to the Module documentation section. Modules are
+ defined with the following format in the groups.dox file:
+
+ #+begin_src c
+ /**
+ * @defgroup name_of_module Readable Name Of Module
+ * @ingroup name_of_parent_module
+ * @{
+ *
+ * @brief One line description of module
+ *
+ * Multiple lines description of module
+ * Can use markdown language features, like
+ * sharp for section headers, etc.
+ */
+ ...
+ /** @} */
+ #+end_src
+
+ All functions between ~@{~ and ~@}~ belong to the same Module. Most
+ modules have already been created, look for defgroup. Some of them
+ are defined in the file ~groups.dox~, because they span over multiple
+ files in the source code.
+
+* DOs and DO NOTs
+
+** Functions Prototypes
+ *DO* comment all functions at their function definition (typically .c
+ file), or, if they are static functions used in a single file,
+ before the function definition.
+
+ *DO NOT* comment /both/ the function definition and the function
+ prototype, or the documentation of the function will be duplicated.
+
+** Doxygen Comments
+ All ~/** ... */~ comments are interpreted by Doxygen as to be added
+ to the documentation.
+
+ If you enter a ~/** ... */~ comment without Doxygen commands in it,
+ all the text of the comment will be appended to the next Doxygen
+ group.
+
+ So, *DO NOT* start comments inside the code with ~/**~, despite the
+ nice coloring of your editor. All these comments make no sense once
+ they are appended to the next function or structure documentation.
+
+ *DO* configure your editor to use your preferred coloring scheme for
+ normal comments :)
+
+** Doxygen keywords
+ Any ~@something~ inside a ~/** ... */~ block is interpreted as a
+ Doxygen keyword. Doxygen stops parsing the entire file if it finds
+ a keyword it does not know. *DO NOT* use your own keywords, *DO* check
+ the generated documentation.
+
+* Modules Structure
+ All functions, macros, variables should belong to a module. *DO* look
+ at the documentation to see the structure, and if you document a
+ function, be sure that it belongs to the right module. *DO NOT* just
+ document a function without enclosing it inside a ~@addtogroup @
+ ... @}~ group, or without adding a ~@ingroup group_name~ before the
+ function definition.