[RTEMS Project] #3704: Review and update Doxygen recommendations

[RTEMS trac]

#3704: Review and update Doxygen recommendations
------------------------------+-----------------------------
  Reporter:  Sebastian Huber  |      Owner:  Sebastian Huber
      Type:  task             |     Status:  assigned
  Priority:  normal           |  Milestone:  6.1
 Component:  doc              |    Version:  6
  Severity:  normal           |   Keywords:  qualification
Blocked By:                   |   Blocking:  3701
------------------------------+-----------------------------
 Review and update the [https://docs.rtems.org/branches/master/eng/coding-
 doxygen-bsp.html Doxygen recommendations].

 Due to the removal of the pre-install build step we can now use Doxygen
 directly with header files in the source tree. It should be possible to
 generate documentation for all architectures and BSPs.

 All code files (headers, C source, assembler) should have an @file entry
 belong to at least one Doxygen group (@ingroup).

 There are a lot of source file in RTEMS (excluding test code and legacy
 network stack):
 {{{
 find bsps cpukit -name '*.[chsS]' | grep -v libnetworking | wc
    4898    4898  187167
 }}}

 Creating the groups and categorizing all code file is a labour intensive
 work package. Therefore it should be discussed if the @brief and
 descriptions for files should be removed. The file content will be covered
 by groups and individual documentation.

 The use of @param should be clarified. It is not clear if the [in], [out]
 or [in,out] should be used. If they should be used, what they mean
 exactly.

--
Ticket URL: <http://devel.rtems.org/ticket/3704>
RTEMS Project <http://www.rtems.org/>
RTEMS Project