From:  "Nicolas B. Pierron" <npierron@mozilla.com>
Date:  22 Nov 2018 01:42:50 Hong Kong Time
Newsgroup:  news.mozilla.org/mozilla.dev.tech.js-engine.internals
Subject:  

Improving our internal documentation.

NNTP-Posting-Host:  2a00:8c40:243:224:3ade:adff:fedf:df5e

Hi,

SpiderMonkey internal documentation is sometimes lacking or out-of-date. With the JIT team we had a meeting to discuss ways to improve upon this state. One of the idea was to open a meta-bug to track internal documentation issues.

If while reading the code you find a place which lacks or has an out-dated documentation, or you just spent 30 minutes on IRC trying to understand the state of the existing code,

Then, take 10s to file a bug as a blocker of:

  Bug SMDOC: https://bugzilla.mozilla.org/show_bug.cgi?id=SMDOC

Then, as a SpiderMonkey developer, you now have the responsibility to fix some of these bugs at your own pace, knowing that in a few years, you might be the person asking these questions.

Also note, that some of this documentation effort, when going in depth in the description of some components might be worth writing a blog post. Readers of the JavaScript blog are more than likely interested in your prose, and might give you the feedback needed to make this documentation understandable to anybody who never saw a SpiderMonkey before.