True when the lines immediately before `node` form a /** @brief ... */ block. The block may sit anywhere from 0 to ~3 blank/decorator lines above the declaration.
(node, src: bytes)
| 1274 | |
| 1275 | |
| 1276 | def _previous_doxygen_brief(node, src: bytes) -> bool: |
| 1277 | """True when the lines immediately before `node` form a /** @brief ... */ |
| 1278 | block. The block may sit anywhere from 0 to ~3 blank/decorator lines |
| 1279 | above the declaration.""" |
| 1280 | start_line = node.start_point[0] |
| 1281 | if start_line == 0: |
| 1282 | return False |
| 1283 | |
| 1284 | # Walk backward from the line just above the declaration. We want to |
| 1285 | # find a closing `*/` first, then verify that the matching `/**` is |
| 1286 | # within reach AND mentions @brief. This handles long doxygen blocks |
| 1287 | # (DSP.h's FixedQueue carries a 16-line @brief) without hand-tuning |
| 1288 | # a fixed lookback window. |
| 1289 | src_text = src.decode("utf-8", errors="replace") |
| 1290 | lines = src_text.split("\n") |
| 1291 | cur = start_line - 1 |
| 1292 | # Tolerate up to 8 lines of pre-declaration noise between the doxygen |
| 1293 | # close and the declaration: blanks, banner comments, `template<...>` |
| 1294 | # clauses, `requires ...` constraints, attributes (`[[nodiscard]]`), |
| 1295 | # access specifiers carried over from a class body. |
| 1296 | skip = 0 |
| 1297 | while cur >= 0 and skip < 8: |
| 1298 | s = lines[cur].strip() |
| 1299 | if ( |
| 1300 | not s |
| 1301 | or s.startswith("//") |
| 1302 | or s.startswith("template") |
| 1303 | or s.startswith("requires") |
| 1304 | or s.startswith("[[") |
| 1305 | or s.startswith("public:") |
| 1306 | or s.startswith("private:") |
| 1307 | or s.startswith("protected:") |
| 1308 | ): |
| 1309 | cur -= 1 |
| 1310 | skip += 1 |
| 1311 | continue |
| 1312 | break |
| 1313 | if cur < 0: |
| 1314 | return False |
| 1315 | if not lines[cur].rstrip().endswith("*/"): |
| 1316 | return False |
| 1317 | # Walk further back until we find `/**` -- look at most 60 lines. |
| 1318 | open_idx = -1 |
| 1319 | for j in range(cur, max(0, cur - 60) - 1, -1): |
| 1320 | if "/**" in lines[j]: |
| 1321 | open_idx = j |
| 1322 | break |
| 1323 | if open_idx < 0: |
| 1324 | return False |
| 1325 | block = "\n".join(lines[open_idx : cur + 1]) |
| 1326 | return "@brief" in block |
| 1327 | |
| 1328 | |
| 1329 | def _previous_doxygen_block_range(node, src: bytes): |