From:  tcampbell@mozilla.com
Date:  06 Jul 2018 01:05:40 Hong Kong Time
Newsgroup:  news.mozilla.org/mozilla.dev.tech.js-engine.internals
Subject:  

SMDOC annotation for in-source documentation

NNTP-Posting-Host:  2620:101:80f2:224:8429:33ef:b6c4:1aee

The codebase contains a number of longer comments detailing key aspects on the SpiderMonkey engine, but these have to been hard to locate. In order to increase visibility of these, we've added a [SMDOC] annotation to many of them with a one line description. This tag can be grepped for locally or in an online index like searchfox.

https://searchfox.org/mozilla-central/search?q=SMDOC&path=js

Let's make an effort to document various complex systems and bring more visibility for old and new committers. At this stage it is better to have too many annotations and we can always remove or rename them later.

Good Things to Annotate (and Document)
- Cross-cutting systems that impact many areas of code base (eg. GC)
- Complex heap structures that JITs or pointer magic access (eg. JSObject layout)
- Hidden optimizations and "optimizations" (eg. MathCache)
- API helpers we expect people to use (eg. CallArgs)
- Complex algorithms without definitive outputs (eg. Register allocation)

These are merely things I believe are useful to surface, but I'm no archivist here so feel free to use your own judgement. Ideas welcome and this is an incremental process.