#3704 accepted task

Review and update Doxygen recommendations

Reported by: Sebastian Huber Owned by: Sebastian Huber
Priority: normal Milestone: 6.1
Component: doc Version: 6
Severity: normal Keywords: qualification
Cc: Blocked By:
Blocking: #3705, #3706

Description

Review and update the 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.

Change History (8)

comment:1 Changed on Feb 26, 2019 at 1:12:31 PM by Sebastian Huber

Blocking: 3705 added

comment:2 Changed on Feb 26, 2019 at 1:23:37 PM by Sebastian Huber

Blocking: 3706 added

comment:3 Changed on Feb 26, 2019 at 1:30:16 PM by Sebastian Huber

Blocking: 3701 removed

comment:4 Changed on Feb 26, 2019 at 1:30:45 PM by Sebastian Huber

Status: assignedaccepted

comment:5 Changed on Apr 4, 2019 at 5:22:51 AM by Sebastian Huber <sebastian.huber@…>

In fbe8a7a/rtems:

doxygen: Rework some Doxygen comments

They are intended as examples in the RTEMS Software Engineering manual.

Update #3704.

comment:6 Changed on Apr 4, 2019 at 5:40:37 AM by Sebastian Huber <sebastian.huber@…>

In 1d48fb5/rtems-docs:

bsp-howto: Move BSP Doxygen recommendations

Update #3704.

comment:7 Changed on Apr 5, 2019 at 5:47:11 AM by Sebastian Huber <sebastian.huber@…>

In 8a8b95aa/rtems:

doxygen: Update _Objects_Build_name()

This is intended as an example in the RTEMS Software Engineering manual.

Update #3704.

comment:8 Changed on Apr 5, 2019 at 7:40:39 AM by Sebastian Huber <sebastian.huber@…>

In ef19112/rtems-docs:

eng: Rework Doxygen guidelines

Update #3704.

Note: See TracTickets for help on using tickets.