Skip to content

Commit 265e7f4

Browse files
committed
feat: update ideas list
1 parent 2334967 commit 265e7f4

File tree

1 file changed

+48
-0
lines changed

1 file changed

+48
-0
lines changed

ideas.md

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1432,4 +1432,52 @@ C, Fortran, JavaScript, Node.js.
14321432

14331433
### Project length
14341434

1435+
350
1436+
1437+
* * *
1438+
1439+
## Extend stdlib's doctesting approach to C examples
1440+
1441+
Linked issue: <https://github.com/stdlib-js/google-summer-of-code/issues/96>
1442+
1443+
### Idea
1444+
1445+
We heavily rely on doctesting (see https://github.com/stdlib-js/stdlib/blob/develop/docs/doctest.md) to ensure that our Markdown and JSDoc examples are correct and do not become out-of-date. However, we currently have no such framework for ensuring that our C source code and Markdown examples are correct.
1446+
1447+
The goal of this project would be to implement doctesting for C source code and associated Markdown examples. While the approach is likely to be similar (e.g., parsing source code in scripts, Markdown code blocks, and in DOXYGEN examples), the technology stack is likely to be different and will require some R&D, especially as we won't be able to rely on things like ESLint. Instead, we'll need other tooling for identifying `// returns` annotations, instrumenting examples to collect return values, resolving source files to compile, compiling source files, executing scripts, and asserting that the output results match expectation.
1448+
1449+
### Expected outcomes
1450+
1451+
As part of our CI workflows and in local development, developers will be able to test that their C examples are correct.
1452+
1453+
### Status
1454+
1455+
stdlib has its own doctesting framework for checking JavaScript examples. This should serve as inspiration and provide an idea of what we are looking for.
1456+
1457+
### Involved software
1458+
1459+
C compilers, AST generators, and stdlib tooling.
1460+
1461+
### Technology
1462+
1463+
C
1464+
1465+
### Other technology
1466+
1467+
None.
1468+
1469+
### Difficulty
1470+
1471+
5
1472+
1473+
### Difficulty justification
1474+
1475+
There is likely a need for R&D to determine the best tools and approach. For JavaScript examples, we are able to rely on the fact that we can lint and execute within the same JavaScript runtime. In this case, there will be additional steps needed to separately instrument, create temporary files, compile, execute, and collect.
1476+
1477+
### Prerequisite knowledge
1478+
1479+
Experience with C and creating tooling will be beneficial.
1480+
1481+
### Project length
1482+
14351483
350

0 commit comments

Comments
 (0)