[RFC]: generate web documentation from JSDoc comments

[Monika887]

Full name

Monika Joshi

University status

Yes

University name

Sagar Institute of Science and Technology Bhopal

University program

Computer Science & Engineering

Expected graduation

2022

Short biography

My Name is Monika Joshi, I'm a completed Bachelor Of Technology in computer science and engineering from Sagar Institute of science and technology Bhopal.I'm from Bhopal the capital of Madhya pradesh with CGPA is 8.61, I’ve participate

• TechGig Code Gladiators 2021(I secured a rank of 157 in the Semi-Finals round)
• Google Code JAM 2021
• 30 Days Google Cloud Program

Technical Skills:
• Frontend: HTML, CSS, JavaScript, React
• Backend: Node.js. SQL , PostgreSQL
Programming Languages
• C, C++, Javascript, Python, Java
• Data Structures and Algorithms
• Strong understanding of algorithmic complexities and problem-solving.

I'm mainly a web developer. I've completed an internship at Wipro, where I develop a home page and login page using Java, Html, css, JavaScript, Database, eclipse id. This experience gave me valuable insights into the inner workings of JavaScript and the deployment process.
In college, I've Build a projects
• All-In-One Data Structure Project
• Exam Hall Seating Arrangement System Project
• Animated Data Structure & Visualization Project

Timezone

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

Contact details

email: monikajoshi6411@gmail.com , https://github.com/Monika887

Platform

Windows

Editor

The platform which I prefer to use is VSCode. The primary reason for the same is its user friendliness along with support of which ecosystems of extensions. It also allows built-in GIT Integration. Also, visual appearance of the editor appreciable.which supports custom themes and code coloring, making coding more enjoyable, I have been using VSCode since I was a freshman in college, and thus I am familiar with it very well.

Programming experience

I started coding when I entered my first year of college in c. After enough practice in c.l I moved to c++ and it became my go-to language for problem solving (DSA). I also studied Object Oriented Programming in Java. Through Full Stack Development, I practiced Javascript in great detail after learning it from multiple platforms for front-end and back-end.Here's some of my recent project:
• All-In-One Data Structure Project
Designed And Implemented All-In-One Data structure project. It is a menu driven Project and works in Data
structure Algorithms(Stack,Queue,Linked List, Searching,Sorting etc).
• Exam Hall Seating Arrangement System Project
Designed And Implemented Exam Hall Seating Arrangement System Project using the technology Java
,HTML,CSS,Javascript,Bootstrap,MySQL.
• Animated Data Structure & Visualization Project
Developed Front_End Project for building HTML,CSS, JS. It is interactive Animation for a variety of Data
Structures(like Stack, Queue, Linked List, Binary Tree).

JavaScript experience

At the beginning of our full stack development course, I learnt all the fundamental concepts of Javascript and ES6 through YouTube. Further, I learnt React for developing interactive user-friendly Ul web pages. Some of my projects are as follows:

• Animated Data Structure & Visualization Project
• Exam hall seating arrangement system project
  Tesla clone, I've also learned JavaScript in the Wipro PJP project and created some web pages.

Node.js experience

In my full-stack projects, I usually utilize Node.js and Express.js for backend development. This includes tasks like database connectivity, API implementation, and file management among others. I also learned in college at node.js

C/Fortran experience

My first programming language was C, which I learned in my first year. I am familiar with the basics, including concepts like pointers, dynamic memory allocation and file system. I haven't learned Fortran yet, but I am open to learning it if required.
For my first-year college project, I built a
All-In-One Data Structure Project- Designed And Implemented All-In-One Data structure project c/c++language and oops concepts. It is a menu driven Project and works in Data structure Algorithms(Stack,Queue,Linked List, Searching,Sorting etc).

Interest in stdlib

I have a good foundation in various tools and technologies relevant to your project, I am eager to leverage my skills to make meaningful contributions. Exploring your project's GitHub repository, I have identified it as an ideal fit for my interests and capabilities. I had previous experiences in hackathons and various tech-related projects.
So, I am eagerly looking forward to the opportunity of contributing to your organization and making a positive impact.
I'm intrigued by stdlib's vision to transform numerical computation online. Its unique combination of JavaScript and C, along with a modular structure, resonates well with my expertise. I'm impressed by its dedication to quality, reflected in meticulous testing and detailed documentation. With stdlib, I envision a future where complex computations are

Version control

Yes

Contributions to stdlib

Work in Progress….

stdlib showcase

Work in Progress….

Goals

The goal of this project is to enhance stdlib's documentation capabilities by creating an in-house JSDoc parser that generates HTML documentation from JSDoc comments. This documentation will better support stdlib's conventions and its modular architecture. Additionally, the parser could be extended to support C source files and make files, which currently use similar documentation practices but require separate parsers due to differences in syntax.

• Develop a JSDoc Parser: Create a custom parser to extract JSDoc comments from JavaScript source files.
• Generate HTML Documentation: Produce user-friendly HTML documentation that reflects stdlib's modularity and conventions.
• Extend Support to Other File Types: Optionally, adapt the parser to handle C source files and make files, requiring separate AST
  parsers for each file type.
  Expected Outcomes:
• Users will have access to detailed HTML documentation for each package, including insights into input/output data types and
  algorithm implementations.
• This will be particularly useful for elementary mathematical functions, where extended JSDoc comments can provide deeper
  understanding.

The objective of this idea is to enhance the documentation generation process for the stdlib project by creating an in-house JSDoc parser that can generate comprehensive HTML documentation from JSDoc comments. Currently, the project has limited support for converting JSDoc comments into HTML docs.

Why this project?

This project aims to create an in-house JSDoc parser and HTML documentation generator for stdlib, a JavaScript library that heavily relies on JSDoc comments for source code documentation. Currently, the project has only basic support for generating HTML docs, and this enhancement would improve documentation navigation, readability, and usability—especially for mathematical functions with detailed input/output type specifications and algorithm explanations.

• This project is a great choice because it aims to enhance the stdlib project by building a custom JSDoc parser that generates HTML documentation. The current documentation system is limited, and this effort will improve accessibility, organization, and modularity

• This project is an excellent choice because it enhances documentation generation, making it more structured, modular, and adaptable to various source file types (JavaScript, C, and Makefiles)

Qualifications

C/C++ was my first programming language, and I’ve since deepened my expertise by studying data structures and algorithms in C++. This strong foundation in low-level programming, combined with my experience as a full-stack developer, makes me well-suited for this project.

I have extensive hands-on experience with JavaScript, Node.js, React, HTML, and CSS technologies directly relevant to this role. Additionally, my background in C/C++ and Native Addons** aligns perfectly with the project’s requirements. Whether through university coursework or independent projects, I’ve consistently applied these skills in practical settings, equipping me to contribute effectively from day one.

I’m confident in my ability to deliver high-quality results and would welcome the opportunity to discuss how my skills can meet the project’s needs.

Prior art

The stdlib library currently uses JSDoc comments for source code documentation but lacks advanced HTML generation capabilities. This project aims to develop a custom JSDoc parser to produce comprehensive, stdlib-specific HTML documentation. The solution will emphasize modularity, consistency with stdlib conventions.
Reference Material:
https://www.jetbrains.com/help/webstorm/creating-jsdoc-comments.html
https://github.com/tj/dox

Commitment

1. Pre-GSoC (Community Bonding Period: ~6 Weeks)
   10 hours/week
   Engage with the community, finalize project milestones, and set up the development environment.
   Total: ~60 hours
2. During GSoC (Coding Period: ~12 Weeks)
   30 hours/week
   Core Hours: 6 hours/day, Monday–Friday (30 hours/week).
   Flexibility: Additional weekend hours (Sat-Sun) as needed to meet deadlines or tackle complex tasks.
   Focus on implementation, mentor meetings, and iterative improvements.
   Total: ~350 hours
3. Post-GSoC (Wrap-up & Maintenance)
   5 hours/week (ongoing)
   Address feedback, improve documentation, and support community integration.
   This plan balances structure with flexibility, ensuring steady progress and alignment with GSoC timelines

Schedule

Here's a 12-week schedule for implementing the custom JSDoc documentation generator, aligned with common open-source program timelines like GSoC:

Community Bonding Period

• Goals:
  • Finalize project requirements with mentors
  • Study stdlib's existing documentation structure
  • Set up development environment
  • Create detailed technical design document

Week 1: Project Infrastructure Setup

• Deliverables:
  • Create tools/doc-generator directory
  • Set up Node.js project with required dependencies
  • Implement basic file scanning (JS only)

Week 2-3: JS Parser Implementation

• Deliverables:
  • Complete AST parser for JS files using Babel
  • Doctrine integration for JSDoc parsing

Week 4-5: Data Model & Core Features

• Deliverables:
  • Complete hierarchical documentation tree
  • Implement namespace resolution for stdlib modules
  • Handle cross-references between functions
  • Support for code examples extraction

Week 6: Midterm Evaluation

• Deliverables:
  • Functional prototype:
    • Parses all JS files in stdlib
    • Generates basic HTML pages
    • Shows parameters/returns
    • Navigation between related functions
  • Demo video showing core functionality

Week 7-8: HTML Generation & Styling

• Deliverables:
  • Complete Handlebars templates for:
    • Module index pages
    • Function detail pages
    • Search page skeleton
  • Implement responsive CSS framework
  • Dark/light theme support
  • Interactive elements:
    • Expandable examples
    • Parameter type toggles

Week 9-10: Advanced Features

• Deliverables:
  • C/Makefile comment parser (basic support)
  • Algorithm documentation renderer
  • Dtype compatibility tables
  • Versioned documentation support
  • PDF export capability

Week 11: Testing & Validation

• Deliverables:
  • 95% test coverage
  • Validation against 500+ stdlib functions
  • Browser compatibility testing
  • User testing

Week 12: Finalization & Handoff

• Deliverables:
  • Complete documentation:
    • User guide
    • Contributor guide
    • Architecture overview
  • Integration with stdlib's build system
  • Final presentation to community
  • Roadmap for future improvements
  • Code hardening and security review

Final Week: Buffer Period

• Activities
  • Address last-minute issues
  • Finalize CI/CD pipelines
  • Mentor code review
  • Prepare for upstream merge

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/Idea: #19

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]

@Monika887 Thank you for opening this RFC. A few comments/questions:

1. Have you explored how stdlib already supports JSDoc documentation generation? If so, what are its limitations?
2. You listed dox above. What other reference implementations for parsing JSDoc can you point to?
3. What are some of the challenges for generating JSDoc web documentation for stdlib, in particular? What can you say about the structure of stdlib that make stdlib somewhat unique compared to other projects?
4. Do you have any mockups for expected output?
5. How will you handle Markdown and math equation parsing which we use fairly heavily in stdlib JSDoc comments?
6. How will you handle/support stdlib's collection of custom types?

[Monika887]

Thank you for reviewing the proposal,
1:Yes, the stdlib library supports JSDoc-based documentation generation using tools like jsdoc or documentation.js. and Example .commitlintrc.js, etc/.links.js, etc. Stdlib fikes support JSdoc documentation. but it has some notable Limitations of stdlib's JSDoc Documentation Generation, Limited Dynamic Module Support., No Built-in CLI for Docs,Complex Namespace Structures, Lack of Interactive Examples, Partial TypeScript Support

2:other reference implementations for parsing JSDoc
https://github.com/jsdoc/jsdoc
https://github.com/jsdoc2md/jsdoc-to-markdown
https://github.com/documentationjs/documentation
https://youtu.be/YK-GurROGIg?si=dfpDFK695-njALJ5

3:The main challenges stem from stdlib's size, modular structure, potential use of namespaces and TypeScript, platform-specific code, custom tags, examples integration, versioning, searchability, and dynamic code aspects. Each of these factors requires specific handling in JSDoc configuration, possibly involving custom plugins, templates, or additional tooling to ensure comprehensive and user-friendly documentation.
The structure of stdlib, being highly modular and extensive with many interdependent modules and functions, amplifies these challenges.

4: Here's a hierarchical mockup of stdlib's documentation output.

5:Unified parser: Use remark/rehype ecosystem for Markdown
Math support: Integrate KaTeX for client-side rendering
Syntax highlighting: Prism.js for code examples
Preprocessing: Extract and transform equations before rendering
Validation & Debugging

6:stdlib's custom types handle:
Type registry: Create a central type definition database
Type relationships: Show inheritance/graphs where applicable
Custom renderers: Special display for ndarrays, buffers etc.
Validation: Ensure type references are resolvable
Type tooltips: Quick documentation on hover
Polymorphic links: Connect dispatch variants to implementations