Opened on 02/26/19 at 13:10:56

Closed on 07/26/23 at 05:05:47

#3704 closed task (fixed)

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 (10)

comment:1 Changed on 02/26/19 at 13:12:31 by Sebastian Huber

Blocking: 3705 added

comment:2 Changed on 02/26/19 at 13:23:37 by Sebastian Huber

Blocking: 3706 added

comment:3 Changed on 02/26/19 at 13:30:16 by Sebastian Huber

Blocking: 3701 removed

comment:4 Changed on 02/26/19 at 13:30:45 by Sebastian Huber

Status: assigned → accepted

comment:5 Changed on 04/04/19 at 05:22:51 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 04/04/19 at 05:40:37 by Sebastian Huber <sebastian.huber@…>

In 1d48fb5/rtems-docs:

bsp-howto: Move BSP Doxygen recommendations

Update #3704.

comment:7 Changed on 04/05/19 at 05:47:11 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 04/05/19 at 07:40:39 by Sebastian Huber <sebastian.huber@…>

In ef19112/rtems-docs:

eng: Rework Doxygen guidelines

Update #3704.

comment:9 Changed on 11/30/22 at 08:51:58 by Sebastian Huber

Milestone: 6.1 → 7.1

comment:10 Changed on 07/26/23 at 05:05:47 by Sebastian Huber

Milestone: 7.1 → 6.1
Resolution: → fixed
Status: accepted → closed

For RTEMS 6, the guidelines in ​https://docs.rtems.org/branches/master/eng/coding-doxygen.html are good enough.

Note: See TracTickets for help on using tickets.