[RFC]: extend stdlib's doctesting approach to C examples

[NishchayRajput]

Full name

Nishchay rajput

University status

Yes

University name

Indian Institute of Technology Bhilai

University program

Bachelor of Technology in Computer Science and Engineering

Expected graduation

2026

Short biography

I am a pre-final year undergraduate student pursuing a Bachelor’s degree in Computer Science and Engineering. From the early days of my college I was deeply passionate about the software development and wanted to explore. During my initials days of college I was introduced to open-source development which caught my interest. But initially I found it challenging to begin. As the time passed I gained the necessary skills and confidence that I can actively contribute to open-source projects and I now I am engaged in it. I am good enough in multiple languages and also strongly believe that language should never be a barrier to development or contribution, instead it is something you can learn along when required. Also I have been the coordinator at OpenLake the opensource club at my institute where we encourage and promote the opensource among the student. Through this I have gained experience in collaborating with peers, organizing events and fostering a community driven development culture.

Timezone

Indian Standard Time ( IST ), UTC+5:30

Contact details

nishchay202@gmail.com

Platform

Linux

Editor

I prefer Visual Studio Code because it is very accessible, efficient and highly customisable. There are variety of extensions and has user-friendly interface which ease developers and improve productivity and workflow. It also provided features like intelligent suggestion and debugging tools help streamline my work.

Programming experience

I have experience in programming and have worked on various projects using different technologies. Here are a few:
Chcommune – A Blogging Platform with Admin Panel : This is the blogging platform where user can post blogs and this is completely manageable by admin panel as well.
Smart Payment System – Cashless Payment with ID Cards: This is an IOT based web application where payments can be made through the ID cards.
Polaris Website – It provides them with detailed insights into campus life, academics, and student experiences. The website serves as a one-stop guide to help students transition smoothly into college life.

JavaScript experience

JavaScript has become a fundamental language in development especially in case of the web development. Almost everyone in the field has some experience with it as web development mostly relies on JavaScript. Many students including me start with JavaScript because it is beginner-friendly and widely used. In my web development journey I have built various web applications both for academic courses and personal projects. This has given me hands-on experience with JavaScript and particularly in backend development using Node.js and Express.js.

One of my favorite features of JavaScript is its ability to use JavaScript both on the client-side and server-side.

One thing I find challenging about JavaScript is its loosely typed nature i.e. it can sometimes lead to unexpected behaviour due to implicit type conversions.

Node.js experience

So as in web developer I have a good amount of experience with Node.js particularly in building backend servers. I have worked upon several project in which I used Node.js along with the Express.js to create RESTful APIs. Along with this have worked with the databse as well like MongoDB, MYSQL or PostgressSQL.

C/Fortran experience

C is one of my favorite programming languages from beginning and throughout my academic journey I had multiple opportunities to work with C across various fundamental courses like Algorithms, Compiler Design, Network Science, Computer Networks, and Operating Systems which allowed me to explore C at a deeper level. From implementing parsers and working with memory management to understanding system-level programming and network protocols, I have gained a strong grasp of C and its applications.

Interest in stdlib

Form the beginning I have been interest towards the maths background and wanted somehow development aspect to put into it. Before I was into opensource I got to know about Gunj Joshi one the core contributor and last year he had a great contribution here and I did saw that I started eventually. Due to my some academic commitment I have not been much active from late march but will be now do so as I am out of it. However I find that stdlib has very interactive community of gitter and has very great code structure. Had difficulty initially as this was my first org which I was contributing for the first time into opensource. And this made me confident enough that I can do much better into opensource and really grow my interest into it. Thank you stdlib community

Version control

Yes

Contributions to stdlib

My contribution to stdlib wer primarily focused on the @stdlib/stats/base/dists/ module where I worked upon the C implementation of the functions. Throughout this I raised multiple PRs and some of them have been merged and other are under review.
Open PRs
Merged PR

While working on the C implementation I saw that there were several function that had dependencies on others. So to enhance the development workflow and to help the future contributors of stdlib I made sure to leave a comment on relevant issue regarding the same. So anyone picking up and issue is aware of these dependencies beforehand and allowing them to efficiently allocate their time and effort.
Dependencies

stdlib showcase

In progress

Goals

So the main goal for this project is to extend the stdlib doctesting framework to support C examples and ensures that all documentation examples remain function, accurate and automatically tested. This will allow us to bring the C documentation testing as the same level of the JavaScript within the stdlib. I aim to achieve the following:

• Automate Testing of C Documentation Examples: Currently C documentation examples are written manually but aren’t verified automatically. So with this we will be introducing the system to parse, extract and execute the C examples.
• Develop JSDoc-Style Parser for C source files
• Implement a Compilation and execution workflow for C examples.
• Integrate the C Examples testing into stdlib workflow.
• Providing clear documentation for the same so future contributors can easily maintain and extend it.

Why this project?

I have always had a soft spot for the C language, and this project immediately caught my attention. It is also a high-priority task for stdlib, making it a great opportunity to contribute meaningfully to the community. Unlike other tasks in stdlib, such as C or JavaScript function implementations, this project focuses on documentation testing and automation an area that many contributors avoid due to its complexity. However I believe taking on challenging projects like this helps an individual grow significantly by improving problem solving skills, learning automation techniques, and gaining a deeper understanding of parsing and documentation testing. My goal is to ensure that the solution is simple, maintainable, and seamlessly integrates with stdlib’s existing framework. This project not only excites me but also presents a chance to work on something impactful that will enhance documentation quality and benefit future contributors.

Qualifications

I have been actively contributing to stdlib by implementing statistical functions in C under @stdlib/stats/base/dists/. While working on these implementations I have gained a strong understanding of stdlib’s code structure, development workflow, and best practices.

I have a solid background in C programming and compiler design thanks to my academic coursework and practical experience. This has given me a good grasp of memory management, parsing, and execution flows in C, which are essential for this project.

Also I have explored DOXYGEN and Markdown-based documentation and have recently dived into stdlib’s JavaScript doctesting framework. By going through the _tools directory, I have gained a basic understanding of its implementation.

I am a quick learner and enjoy tackling challenging problems. I prefer learning by implementing, which gives me an advantage in projects like this. Through my contributions, I have also sharpened my debugging, documentation, and problem-solving skills, making me well-prepared to take on this project.

Prior art

TODO

Commitment

I don’t have any other academic commitments during the contribution period, as it falls during my vacation. This allows me to fully dedicate my time to the project and be more efficient and productive. In August my college semester will begin, but since it’ll be the early phase, it won’t be an issue. If needed, I’ll try to get ahead on work beforehand to ensure a smooth workflow.

Schedule

Assuming a 12 week schedule,

• Community Bonding Period:
  • In this week I will more focus over the prototype a minimal parser
  • I intent to experiment with the compiling and running example snippets extracted from the comments
  • Documenting about the potential challenges/edge cases might occur and discuss up with the mentors

---

• Week 1-2: In this week I will focusing over the implementation of parser that will extract and isolates C examples form the documentation comments. Also will write tests to verify that the parser extracts examples accurately.

• Week 3-4: For this week will be working on extracting, compiling and running example code from C documentation. I will also start integrating this within the framework.

• Week 5-6: I would be focusing over the past week works will refine them based on the feedback from mentors, fixing bugs and code optimisation. Half a week will be as a buffer week as while development there are very high chances of getting bugs and issues so address them.

---

MidTerm

---

• Week 7-8: We already have the mechanism to verify the expected and the actual output for the JS. For this I need to update those or have different.

• Week 9-10: In this week I would approach for the integration of the parser within existing framework along with the automation process.

• Week 11-12: Similar to the weeks before midterm I would here review all the features and make final improvements, with comprehensive documentation for future contributors and thorough testing. Half a week will be as a buffer to address the bugs and feedback from the mentors in order to freeze the code.

---

• Final Week: Submitting the final code to the mentor, writing a blog post or final report summarising the work done and address the last minute feedback.

Notes:

• The community bonding period is a 3 week period built into GSoC to help you get to know the project community and participate in project discussion. This is an opportunity for you to setup your local development environment, learn how the project's source control works, refine your project plan, read any necessary documentation, and otherwise prepare to execute on your project project proposal.
• Usually, even week 1 deliverables include some code.
• By week 6, you need enough done at this point for your mentor to evaluate your progress and pass you. Usually, you want to be a bit more than halfway done.
• By week 11, you may want to "code freeze" and focus on completing any tests and/or documentation.
• During the final week, you'll be submitting your project.

Related issues

Issue #96

Checklist

• I have read and understood the Code of Conduct.
• I have read and understood the application materials found in this repository.
• I understand that plagiarism will not be tolerated, and I have authored this application in my own words.
• I have read and understood the patch requirement which is necessary for my application to be considered for acceptance.
• I have read and understood the stdlib showcase requirement which is necessary for my application to be considered for acceptance.
• The issue name begins with [RFC]: and succinctly describes your proposal.
• I understand that, in order to apply to be a GSoC contributor, I must submit my final application to https://summerofcode.withgoogle.com/ before the submission deadline.

[kgryte]

@NishchayRajput Thanks for opening this RFC. A few comments/questions:

1. How are you planning on capturing output and results? For JS, we can instrument and then run through a new vm instance. For C, it looks like we'd need another mechanism, so I'd be curious to how you are thinking we'd pull this off.
2. One of the nice aspects of our JS doctesting framework is that we are able to instrument such that we retain accurate line number information. With C, it is less clear to me how we'll preserve that information after code transformation. Perhaps you've given some thought to this?
3. What does an MVP look like for you and at what point during the 12 weeks will you have a working prototype?
4. There seem to be a variety of components you'll need to pull this project off. What are the various packages/utilities that you'll need to create and how will you go about separating concerns? e.g., parsing, extracting, etc.

[NishchayRajput]

How are you planning on capturing output and results? For JS, we can instrument and then run through a new vm instance. For C, it looks like we'd need another mechanism, so I'd be curious to how you are thinking we'd pull this off.

So for this I have planned in a way like first after the extraction of the code snippet we can transform into the C program and compiler using the gcc/clang and their output can be captured can store to a temp file if required. Then we can compare the results as similar to the JS implementation. And in case of the runtime exception and the infinite loops we can include the timeout base execution and error handling logic that captures sdterr output. However I am not really sure with the timeout base execution will be the best approach. Hope you could share some opinion on this.

One of the nice aspects of our JS doctesting framework is that we are able to instrument such that we retain accurate line number information. With C, it is less clear to me how we'll preserve that information after code transformation. Perhaps you've given some thought to this?

For this we can use the C preprocessor #line directive . So it tells compiler about that it comes from the specified line number.

#line 42 "README.md"

So this will tell that compiler that codes comes from 42 line number in readme and error is not in the temp file.On top of that we can also keep a small map like a .json file tracks which temporary files came from which Markdown or Doxygen comments. This map will help with debugging showing better error messages, and integrating into CI pipelines

What does an MVP look like for you and at what point during the 12 weeks will you have a working prototype?

So it should be able to demonstrate the extraction, execution and validation cycle. So in the extraction part C snippet from Markdown file or Doxygen comment is extracted and transformed into compilable form and then compile it using the gcc and then capture its output and validate against the expected result. For the working prototype i believe we could achieve around the end of 7-8 week as specified in timeline. And the remaining week will be used focus on improving the reliability and integration into the CI system for use by contributors and maintainers

There seem to be a variety of components you'll need to pull this project off. What are the various packages/utilities that you'll need to create and how will you go about separating concerns? e.g., parsing, extracting, etc.

So i would break it into the modular components and each would be responsible for a specific task. Separation of concerns will ensure that the system is maintainable, testable and easy to expand in the future case. We can have few utilities like example extractor which will extract the snippets from Markdown files or Doxygen-style comments source files which can be either done using th markdown-it or we can createa a simple regex-based extractor . Next we have the utility executor for the extracted code testing where we will wrap the snippet into the standalone C program for compilation with required headers using clang or GCC via a child process. Here we will capture the output and std-error if any. Then we will have an output validator which will compare the output with the expected output as similar to the JS implementation and at last we will have an reporter and mapper utility which will be responsible for showing the test result in a better way. I would highlight which specific example passed or failed compares actual and expected output and maps any runtime or the compiler error with the line number .