From e2022f588492d5c117743b6b13801940f4a4b03e Mon Sep 17 00:00:00 2001 From: Ken Sarkies Date: Thu, 7 Mar 2013 11:14:06 +1030 Subject: Repair to documentation (most documented files) to remove errors, duplications and inconsistencies. File lib/stm32/f1/pwr.c - all code removed as it duplicates that in common/pwr_common.c Remaining changes do not affect code. Compiles OK. TODO efm32 has no code so generates no modules TODO F2 needs pwr.c TODO L1 needs dma.h and dma.c --- doc/HACKING | 43 ++++++++++++++++++++++++++----------------- 1 file changed, 26 insertions(+), 17 deletions(-) (limited to 'doc/HACKING') 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 -- cgit v1.2.3