To expand on Dave's first priority: as a newbie working on SpiderMonkey code, I find garbage collection to be the area where the documentation that I could find is least helpful. That includes the documents: https://developer.mozilla.org/en-US/docs/SpiderMonkey/JSAPI_User_Guide#Garbage_collection https://developer.mozilla.org/en-US/docs/SpiderMonkey_Garbage_Collection_Tips https://developer.mozilla.org/en-US/docs/SpiderMonkey/Internals/Garbage_collection https://developer.mozilla.org/en-US/docs/SpiderMonkey/JSAPI_Reference https://wiki.mozilla.org/Sfink/Draft_-_GC_Pointer_Handling and (a bit more helpful than the rest) js/src/gc/Root.h
I'd really like to see a single document on how to make C++ code that deals with gcthings safe for all garbage collectors that ever interact with them. It should have enough background on the garbage collectors used in Mozilla code so I can understand the interactions, but I don't think I need to know how big arenas are, probably not even that they exist. It should document best current practice, which seems to involve RootedObject, RootedValue, and HandleObject, and not many of the other things floating around on the current wiki pages (JSRootedObject? ObjectRoot? "extra" member of JSFunctionSpec?). And it would be really useful to have information about common crash scenarios - "if the stack trace in gdb looks like this, it may mean...". On a separate note, I'm wondering why SpiderMonkey API documentation is edited on a wiki and not as part of the source code. As Nicholas points out in bug 784880, wiki documentation is far less likely to be up to date than comments in the source code. Other projects write all API documentation in the form of doc comments in the source code, and have a tool such as doxygen extract the comments and produce nice web pages - e.g.: http://icu-project.org/apiref/icu4c/classSimpleDateFormat.html Why not SpiderMonkey? Norbert On Sep 20, 2012, at 19:56 , Dave Mandelin wrote: > On Friday, September 14, 2012 4:05:53 AM UTC-7, Till Schneidereit wrote: >> My question to the list is, then, what you all think I should work on >> with the highest priority. Obviously, there are still a lot of areas >> of the project that I don't know too well, so I'll have to see what >> even makes sense for me to write documentation about. Also, I'm not >> sure that updating the embedding API even makes sense currently, what >> with the ongoing work on implementing a C++ API and all. > > Good questions. It's really up to you, but I can provide some background: > > Jeff's right--it's unlikely we'll be making big changes to the embedding API > in the near future. But that doesn't make it obvious what to do: on the one > hand, doc improvements won't be obviated in the near future; on the other, > embedding APIs aren't high priority right now. If you want to do some work on > them, I think it'd be worthwhile enough--useful now, and could help with > designing the APIs or creating examples of API docs for the future. > > Other things I care about: > > - Docs on the rooting API. Helping with this would be much appreciated. See > https://bugzilla.mozilla.org/show_bug.cgi?id=789551 > - Docs on compartments. I don't think we have any kind of overview or > tutorial, which is pretty bad > - Improved basic docs on building and testing > - Docs on major internals concepts > > Dave > _______________________________________________ > dev-tech-js-engine-internals mailing list > [email protected] > https://lists.mozilla.org/listinfo/dev-tech-js-engine-internals _______________________________________________ dev-tech-js-engine-internals mailing list [email protected] https://lists.mozilla.org/listinfo/dev-tech-js-engine-internals
