Parse a /** ... */ comment block. Returns (brief: str, description: str). Strips leading * and processes @brief, @param, @return tags.
(raw: str)
| 176 | # ────────────────────────────────────────────────────────────────────────────── |
| 177 | |
| 178 | def _clean_doc_comment(raw: str) -> tuple: |
| 179 | """ |
| 180 | Parse a /** ... */ comment block. |
| 181 | Returns (brief: str, description: str). |
| 182 | Strips leading * and processes @brief, @param, @return tags. |
| 183 | """ |
| 184 | lines = raw.replace('\r', '').split('\n') |
| 185 | brief = "" |
| 186 | desc_lines = [] |
| 187 | for line in lines: |
| 188 | l = line.strip().lstrip('*').strip() |
| 189 | if not l: |
| 190 | continue |
| 191 | if l.startswith('@brief'): |
| 192 | brief = l[len('@brief'):].strip() |
| 193 | elif l.startswith('@class') or l.startswith('@struct') or l.startswith('@enum'): |
| 194 | continue # skip redundant tags |
| 195 | elif l.startswith('@param'): |
| 196 | parts = l.split(maxsplit=2) |
| 197 | if len(parts) >= 3: |
| 198 | desc_lines.append(f'- **`{parts[1]}`**: {parts[2]}') |
| 199 | elif len(parts) == 2: |
| 200 | desc_lines.append(f'- **`{parts[1]}`**') |
| 201 | elif l.startswith('@return'): |
| 202 | desc_lines.append(f'*Returns*: {l[7:].strip()}') |
| 203 | elif l.startswith('@note'): |
| 204 | desc_lines.append(f'> **Note:** {l[5:].strip()}') |
| 205 | elif l.startswith('@warning'): |
| 206 | desc_lines.append(f'> **Warning:** {l[8:].strip()}') |
| 207 | elif l.startswith('@'): |
| 208 | continue # skip unknown tags |
| 209 | else: |
| 210 | if brief: |
| 211 | desc_lines.append(l) |
| 212 | # If no @brief yet, first plain line becomes brief |
| 213 | if not brief: |
| 214 | brief = l |
| 215 | return brief, '\n'.join(desc_lines) |
| 216 | |
| 217 | # ────────────────────────────────────────────────────────────────────────────── |
| 218 | # Balanced-paren macro argument extractor |
no outgoing calls
no test coverage detected