Enhance documentation for various structures with detailed descriptions and formatting improvements

include/aaruformat/structs/optical.h

@@ -21,36 +21,65 @@
 
 #pragma pack(push, 1)
 
-/**Contains list of optical disc tracks */
-typedef struct TracksHeader {
-    /**Identifier, <see cref="BlockType.TracksBlock" /> */
-    uint32_t identifier;
-    /**How many entries follow this header */
-    uint16_t entries;
-    /**CRC64-ECMA of the block */
-    uint64_t crc64;
+/** \file aaruformat/structs/optical.h
+ *  \brief On-disk structures describing optical disc tracks (Track list block).
+ *
+ *  An optical tracks block (identifier == BlockType::TracksBlock) stores a list of \ref TrackEntry
+ *  records describing the logical layout of tracks and sessions for CD/DVD/BD and similar media.
+ *
+ *  Layout:
+ *    TracksHeader (fixed)
+ *    TrackEntry[ entries ] (array, packed)
+ *
+ *  CRC semantics:
+ *   - TracksHeader::crc64 is a CRC64-ECMA over the contiguous TrackEntry array ONLY (header excluded).
+ *   - For legacy images (imageMajorVersion <= AARUF_VERSION_V1) a byte swap is applied when verifying.
+ *
+ *  Field semantics (TrackEntry):
+ *   - sequence: Logical track number (1..99 typical for CD). Values outside that range may encode extras.
+ *   - type: Value from \ref TrackType (Audio, Data, Mode variants, etc.).
+ *   - start / end: Inclusive Logical Block Address (LBA) bounds for the track. end >= start.
+ *   - pregap: Number of sectors of pre-gap *preceding* the track's first user-accessible sector (can be 0 or negative
+ *             if representing lead-in semantics; negative interpretation is implementation-defined).
+ *   - session: Session number starting at 1 for multi-session discs (1 for single session).
+ *   - isrc: 13-byte ISRC (raw code, no terminating null). If fewer significant characters, remaining bytes are 0.
+ *   - flags: Bitmask of track/control flags. Unless otherwise specified, recommended mapping (mirrors CD subchannel Q
+ *            control bits) is: bit0 Pre-emphasis, bit1 Copy permitted, bit2 Data track, bit3 Four-channel audio,
+ *            bits4-7 reserved. Actual semantics may be extended by the format specification.
+ *
+ *  Invariants / validation recommendations:
+ *   - identifier == BlockType::TracksBlock
+ *   - entries * sizeof(TrackEntry) bytes are present after the header in the block image.
+ *   - 1 <= sequence <= 99 for standard CD tracks (non-conforming values allowed but should be documented).
+ *   - start <= end; pregap >= 0 (if negative pregaps unsupported in implementation).
+ *   - ISRC bytes either all zero (no ISRC) or printable ASCII (A-Z 0-9 -) per ISO 3901 (without hyphen formatting).
+ */
+
+/** \struct TracksHeader
+ *  \brief Header for an optical tracks block listing track entries.
+ */
+typedef struct TracksHeader
+{
+    uint32_t identifier;  ///< Block identifier (must be BlockType::TracksBlock).
+    uint16_t entries;     ///< Number of TrackEntry records following this header.
+    uint64_t crc64;  ///< CRC64-ECMA of the TrackEntry array (header excluded, legacy byte-swap for early versions).
 } TracksHeader;
 
-/**Optical disc track */
-typedef struct TrackEntry {
-    /**Track sequence */
-    uint8_t sequence;
-    /**Track type */
-    uint8_t type;
-    /**Track starting LBA */
-    int64_t start;
-    /**Track last LBA */
-    int64_t end;
-    /**Track pregap in sectors */
-    int64_t pregap;
-    /**Track session */
-    uint8_t session;
-    /**Track's ISRC in ASCII */
-    uint8_t isrc[13];
-    /**Track flags */
-    uint8_t flags;
+/** \struct TrackEntry
+ *  \brief Single optical disc track descriptor (sequence, type, LBAs, session, ISRC, flags).
+ */
+typedef struct TrackEntry
+{
+    uint8_t sequence;  ///< Track number (1..99 typical for CD audio/data). 0 may indicate placeholder/non-standard.
+    uint8_t type;      ///< Track type (value from \ref TrackType).
+    int64_t start;     ///< Inclusive starting LBA of the track.
+    int64_t end;       ///< Inclusive ending LBA of the track.
+    int64_t pregap;    ///< Pre-gap length in sectors preceding track start (0 if none).
+    uint8_t session;   ///< Session number (1-based). 1 for single-session discs.
+    uint8_t isrc[13];  ///< ISRC raw 13-byte code (no null terminator). All zeros if not present.
+    uint8_t flags;     ///< Control / attribute bitfield (see file documentation for suggested bit mapping).
 } TrackEntry;
 
 #pragma pack(pop)
 
-#endif //LIBAARUFORMAT_OPTICAL_H
+#endif  // LIBAARUFORMAT_OPTICAL_H