aboutsummaryrefslogtreecommitdiff
path: root/doc/HACKING
diff options
context:
space:
mode:
Diffstat (limited to 'doc/HACKING')
-rw-r--r--doc/HACKING43
1 files changed, 26 insertions, 17 deletions
diff --git a/doc/HACKING b/doc/HACKING
index 07fb872..4863676 100644
--- a/doc/HACKING
+++ b/doc/HACKING
@@ -28,23 +28,32 @@ Markup
------
Each family has been given a group name that will allow subgrouping of API
-functions and defines in the documentation.
-
-The header and source files for each family must have a heading section
-in which an @defgroup defines the group names. For a peripheral xxx the
-header will have a group name xxx_defines and the source file will have
-xxx_file. This will allow the group to appear separately. An @ingroup must
-be provided to place the group as a subgroup of the appropriate family
-grouping. Note that @file is not used.
-
-Common header and source files must have an @addgroup to include its
-documentation into the appropriate peripheral group. These must not have any
-reference to family groupings to allow them to be incorporated into multiple
-family groups.
-
-Each function must have a header with an @brief, and where appropriate
-@parameter and @return elements. These must describe the allowable parameter
-ranges preferably with reference to a suitable define.
+functions and defines in the documentation.
+
+The header and source files for each peripheral in each family must have a
+heading section in which an @defgroup defines the group name for the particular
+peripheral. This group name will be the same across all families as each one
+is documented deparately. Thus for a peripheral xxx the header will have a
+group name xxx_defines and the source file will have xxx_file. This will allow
+the group to appear separately. An @ingroup must be provided to place the group
+as a subgroup of the appropriate family grouping. Note that @file is not used.
+
+The heading section must include the version number and date and authors names
+plus a license reference. Any documentation specific to the family can be
+included here. If there are common files included then their documentation will
+appear in a separate section.
+
+Common header and source files that are included into a number of families must
+have an @addgroup to include its documentation into the appropriate peripheral
+group. These headings may include authors and any specific descriptions but the
+date and version number must be omitted as it will be included from the family
+files. There must not be any reference to family groupings as these common files
+will be incorporated into multiple family groups.
+
+Each helper function must have a header with an @brief, and where appropriate
+additional description, @parameter and @return elements. These latter must
+describe the allowable parameter ranges preferably with reference to a suitable
+define in the corresponding header file.
The Doxyfile for a family must include input files from the header and source
subdirectories, as well as all needed common files. The common files can be