AP_Logger: Add enum information to VER log message metadata

[shancock884]

The aim of this PR is to add help text for the VER and FILE log messages (linked to issue #26088).

Implemented by adding the relevant comment tags into AP_Logger.cpp

As well as just adding the field descriptions, I wanted to include the enumeration information for the BT, BST and BU fields of the VER message. As there are sets of #defines and not actual enums, I made the following updates:

• Add support to enum_parse.py to extract #define sets enclosed between @LoggerEnum and @LoggerEnumEnd comment tags.
• Add @LoggerEnum and @LoggerEnumEnd comment tags around HAL_BOARD and HAL_BOARD_SUBTYPE defines in AP_HAL_Boards.h.
• Add @LoggerEnum and @LoggerEnumEnd comment tags around APM_BUILD defines in AP_Vehicle_Type.h.

Tested by running parse.py for each vehicle type, and checking the output.
As example, this is the output for the VER message in the .rst output file used to create the wiki page (truncated here to save space):

+--------+----------+-------------------------------------------------------+
| TimeUS | μs       | Time since system startup                             |
+--------+----------+-------------------------------------------------------+
| BT     | enum     | Board type                                            |
|        |          | Values:                                               |
|        |          |                                                       |
|        |          | +-------------------+----+----------+                 |
|        |          | | HAL_BOARD_SITL    | 3  |          |                 |
|        |          | +-------------------+----+----------+                 |
|        |          | | HAL_BOARD_SMACCM  | 4  | unused   |                 |
|        |          | +-------------------+----+----------+                 |
|        |          | (etc)                                                 |
+--------+----------+-------------------------------------------------------+
| BST    | enum     | Board subtype                                         |
|        |          | Values:                                               |
|        |          |                                                       |
|        |          | +-----------------------------------------+------+--+ |
|        |          | | HAL_BOARD_SUBTYPE_NONE                  | -1   |  | |
|        |          | +-----------------------------------------+------+--+ |
|        |          | | HAL_BOARD_SUBTYPE_LINUX_NONE            | 1000 |  | |
|        |          | +-----------------------------------------+------+--+ |
|        |          | (etc)                                                 |

[peterbarker]

Could we get a PR for just the message documentation without enumerations, please? That would give immediate value.

We're already a little over-enthusiastic about what we're parsing out of the C++ code; it took a lot of convincing to even allow parsing out of enum-classes!

Parsing out #define lists is, perhaps a little too much. We could instead look at changing these enumerations to be enum-class instead - that would be a DevCall topic given the extent of that change. This PR (after rebasing on top of a merge-to-master of just the message stuff) would be a good talking point for that topic.

[shancock884]

Sure no problem - small steps :-).... New PR created #26311.

[peterbarker]

Merged the other one - rebase, please?

[shancock884]

I hadn't thought I was opening up a controversial topic! Sorry for that :-).... I can appreciate that parsing the source code in this way may lead to cases where compiler-legitimate code changes end up breaking this parsing - and that is probably even more plausible with #defines.
I'm guessing that these particular cases have to be #defines as they are used by the pre-processor.
I was thinking that the idea of only parsing #defines between specific comment tags (@LoggerEnum/@LoggerEnumEnd) may decrease the risk.

More of a nice to have to no rush on having the debate, and if it is preferred to reject, no worries!

One idea instead could be to use add to the field description something like "See HAL_BOARD_* in AP_HAL_Boards.h", so that at least users have some clue on how to know what any given value means.

[peterbarker]

@shancock884 needs a rebase.

Marking for DevCall to see if we're OK with this additional parsing.

[shancock884]

needs a rebase.

Marking for DevCall to see if we're OK with this additional parsing.

Rebase done, and checked that output is as expected.

[IamPete1]

Maybe we have it somewhere, and not a blocker for this PR. But it would be great to document the various @ tricks for logger and param metadata.