Discussion : Documentation/Code Mismatch for the parse() method 🗣
This discussion is about a discrepancy I found where the project's internal documentation promises a "Parse" feature that is currently missing from the code. I am seeking guidance on whether we should fix the code or update the manual.
Context
While researching the codebase for potential GSoC 2026 contributions, I identified a significant discrepancy. The project's documentation in src/clause.js (Line 22) and src/contract.js (Line 22) explicitly tells developers:
"Set the data for the clause... by calling the parse method and passing in natural language text that conforms to the template grammar."
src/clause.js
src/contract.js
However, this method is missing from the source code, which leads to a TypeError for any developer following these instructions. It appears this was an intentional architectural change in the past, but the documentation was never updated to reflect it.
Detailed Description
I would like to propose two ways to resolve this inconsistency, and I am curious which one the maintainers prefer for the upcoming cycle:
Option 1 (The Feature Fix): Re-implement the parse() and generateText() (Writing) methods in the core library. This would fulfill the documentation's promise and provide a much more intuitive "out-of-the-box" experience for new developers.
Option 2 (The Documentation Fix): Remove the misleading JSDoc instructions and update the manual to reflect that these operations are now handled by external engines.
Discussion : Documentation/Code Mismatch for the parse() method 🗣
This discussion is about a discrepancy I found where the project's internal documentation promises a "Parse" feature that is currently missing from the code. I am seeking guidance on whether we should fix the code or update the manual.
Context
While researching the codebase for potential GSoC 2026 contributions, I identified a significant discrepancy. The project's documentation in src/clause.js (Line 22) and src/contract.js (Line 22) explicitly tells developers:
"Set the data for the clause... by calling the parse method and passing in natural language text that conforms to the template grammar."
src/clause.js
src/contract.js
However, this method is missing from the source code, which leads to a TypeError for any developer following these instructions. It appears this was an intentional architectural change in the past, but the documentation was never updated to reflect it.
Detailed Description
I would like to propose two ways to resolve this inconsistency, and I am curious which one the maintainers prefer for the upcoming cycle:
Option 1 (The Feature Fix): Re-implement the parse() and generateText() (Writing) methods in the core library. This would fulfill the documentation's promise and provide a much more intuitive "out-of-the-box" experience for new developers.
Option 2 (The Documentation Fix): Remove the misleading JSDoc instructions and update the manual to reflect that these operations are now handled by external engines.