Skip to content

backend/sdoc_source_code: parse SDoc nodes from source files #2272

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 26, 2025

Conversation

stanislaw
Copy link
Collaborator

@stanislaw stanislaw commented May 25, 2025

This addresses #2231 for C/C++.

  1. Lark parser is introduced for parsing code comments. Besides @relation markers, now the arbitrary nodes can be parsed as well, for example:
/**
 * Some text.
 *
 * @relation(REQ-1, scope=function)
 *
 * INTENTION: Intention...
 *
 * INPUT: This
 *        is
 *        a statement
 *        \n\n
 *        And this is the same statement's another paragraph.
 *
 * EXPECTED_RESULTS: This is a comment.
 */
void test_case_1(void) {
    print("hello world\n");
}
  1. Using CAPITALIZED_NAME: <...> was the most straightforward both in terms of parsing and interfacing with the existing SDoc convention where the field names are capitalized. I tested \n\n to work successfully for creating paragraphs in both Doxygen and SDoc HTML.

  2. Note that the strictdoc.toml has this important config option now:

source_nodes = [
  { "tests/" = { uid = "TEST_DOC", node_type = "TEST_SPEC" } }
]

...which gives a hint to the source node parser where to inject the auto-generated nodes and which type they should be (in this case description.sdoc has TEST_DOC and defines a grammar with SECTION and TEST_SPEC).

  1. I was not sure how to auto-generate sections, so I went with sorting them according to the source code function paths.

The feature is super-raw but I prefer to merge it and be testing the integration early.

Related to: #2231

@stanislaw stanislaw added this to the 2025-Q2 milestone May 25, 2025
@stanislaw stanislaw force-pushed the stanislaw/test_descriptions branch from 7cd6898 to df8b2cb Compare May 25, 2025 21:54
@stanislaw stanislaw merged commit 03fb9d6 into main May 26, 2025
23 checks passed
@stanislaw stanislaw deleted the stanislaw/test_descriptions branch May 26, 2025 18:28
@stanislaw
Copy link
Collaborator Author

cc @thseiler @haxtibal @Master5

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant