Doc: fix and improve doxygen grouping of boards_common #8189
Doc: fix and improve doxygen grouping of boards_common #8189miri64 merged 15 commits intoRIOT-OS:masterfrom
Conversation
smlng
added
Area: boards
miri64
left a comment
miri64
left a comment
There was a problem hiding this comment.
IMHO doc.txts should only be kept to a minimum. They should only be used for packages, pseudo-modules and the main modules like drivers, sys, etc.
boards/common/arduino-mkr/doc.txt
Outdated
| */ | ||
|
|
||
| /** | ||
| * @defgroup boards_common_arduino-mkr Arduino MKR Common |
There was a problem hiding this comment.
Why create the group here and not leave the definition in board_common.h?
There was a problem hiding this comment.
I find it more convenient to have the @defgroups in doc.txt to allow for extended description and documentation of a group, having this in the header file makes the boiler plate of that file (IMHO) rather long. Though, at the moment, there is no such description for these groups - so if yo insist, I can move that (back) to the header file.
There was a problem hiding this comment.
@miri64 is this blocking for you, i.e., would you rather have this changed, or can we move on (for now)?
There was a problem hiding this comment.
It kind of is...
having this in the header file makes the boiler plate of that file (IMHO) rather long.
Why is that a problem? I see it rather as a benefit. If the detailed doc is somewhere hidden in a doc file noone will read it (or even worse edit it on a major change). If the description however is directly attached to the code chances are higher that people will find it (especially if it is a well written long-ish documentation block) ;-).
There was a problem hiding this comment.
maybe we should clarify that later on. I still favour my approach of using doc.txt for defining doc groups and optionally add more extensive information there.
If the detailed doc is somewhere hidden in a doc file noone will read it
I don't agree with this argument, because the doc.txt resides in the root/main directory not in some subdirectories and their name (again: doc.txt) should be rather tempting to look at to everyone searching for documentation, or not?
Anyway, as in this case the doc.txt only contains the @defgroup its simpler to have it in the header.
There was a problem hiding this comment.
IMHO (and why it was introduced in the first place) the doc.txt approach is a workaround for modules where we do not have a file to put it in. As you might have noticed, it still uses C-syntax to let doxygen be able to read that file at all. The beauty of Doxygen is that it can reside with the code, so why not use it?!??
| */ | ||
|
|
||
| /** | ||
| * @defgroup boards_common_frdm NXP FRDM Common |
boards/common/iotlab/doc.txt
Outdated
| */ | ||
|
|
||
| /** | ||
| * @defgroup boards_common_iotlab IoTlab Common |
boards/common/msb-430/doc.txt
Outdated
| */ | ||
|
|
||
| /** | ||
| * @defgroup boards_common_msb-430 MSB-430 common |
boards/common/msba2/doc.txt
Outdated
| */ | ||
|
|
||
| /** | ||
| * @defgroup boards_common_msba2 MSB-A2 common |
boards/common/nucleo/doc.txt
Outdated
| */ | ||
|
|
||
| /** | ||
| * @defgroup boards_common_nucleo STM Nucleo common |
boards/common/nucleo32/doc.txt
Outdated
| */ | ||
|
|
||
| /** | ||
| * @defgroup boards_common_nucleo32 STM Nucleo32 common |
smlng
force-pushed
the
doc/boards_common
branch
from
c7c0054 to
108aa7d
Compare
|
comments addressed |
|
also compiled docs and checked grouping, this PR fixes wrong grouping of nrf52 board currently visible in our doc + several other groupings |
|
Your last commit is prefixed |
|
Apart from that: confirmed that doc is fixed now. |
smlng
force-pushed
the
doc/boards_common
branch
from
108aa7d to
b1df79a
Compare
oh damn ... anyway, fixed the typo |
|
@miri64 happy? I think we should get our doc right again 😉 |
3 participants
This started of with a bug in the current docu after #8058 was merged where nrf52 common group appeared right at the module root (https://doc.riot-os.org).
This PR adds (or corrects) a dedicated doxygen group for every board group in
boards/commonand also fixes grouping for STM nucleos. I know there is (a lot) more to do but another step is taken here to enhance the documentation.