I must say that public facing API is well documented right in the header files. Each class and majority of important functions have long comments[1]. So claiming that V8 has an anti-documenation culture is incorrect. Next I would like to note that V8 is surely open to patches that improve documentation of public V8 interfaces. I don't remember a lot of those patches flying in though.
Finally, documenting internals is completely different from documenting API. I don't think it is feasible to maintain such documentation. Internals exist only to rely on them in an extreme cases and in such extreme cases reaching to V8 developers directly or reading the source code is the only way to get correct and what is more important up to date information given how things are constantly in flux.
I apologize if you got the impression I was claiming you don't document your public-facing APIs. I'm talking about V8 as a system; intended behaviors and recommended usage patterns and strategies, documentation of downsides and weaknesses and such. The debug-related parts of the 'public' (? not sure if they're actually public) API were very poorly documented when last I checked, though - some of the debug flags you can pass to d8 were only documented in old obscure blog posts.
It is true that debugging[1] options are not well documented, however it is also true that they are intended for use only in exceptional cases or by V8 developers. Many of them are not even available in release build of V8 that is shipping with Chrome (like disassembler or ability to trace IC transitions, which is a shame).
I would say that I am a bit torn on this issue.
First of all, I would love anybody using V8 to be able to troubleshoot issues they are running to as easily as possible. Ideally you should see your source annotated with optimization suggestions and internal V8 information translated into digestible form. I experimented with some ways of doing that but sadly I totally lack time to make a product out of that.
However I am not sure making some static cookbook of performance patterns is the right way to go here. It certainly can help in the short run, but in the long run its the uniformity of optimizations on V8 side and general shape of your code that matters. I fear cargo cult blindly following such a cook book without making an attempt to understand.
Additionally I fear that it is extremely hard to make and maintain such a cook book given that VMs consist of extremely many moving components and sometimes you can't decompose performance of an application into performance of small patterns, they interfere with each other. Understanding of internals, or understanding of how and where get the information on internals is much more important.
Maybe I am wrong, but I am doing my best to actually help people to become interested in V8 internals instead of following blindly recommendations.
[1] note: we are not talking about JavaScript debugger itself which should be relatively well documented as far as I understand, C++ header files look like they contain a lot of comments and I know there is a protocol description on the wiki.
I definitely agree with you on the reasons why concrete performance rules/documentation is dangerous - I historically have tried to advocate for better introspection/debugging tools instead of just lists/documents. But so far the reaction to those has been pretty cold; it seems as if most engine devs I speak to view introspection tools/APIs as equivalent to documenting (and thus locking in) internals and runtime design details. I can understand how shipping a product like this as a part of a large software org is pretty hard - it's difficult to establish how many customers it has and what the benefits will be.
Not really sure how we get out of the spot we're in, unfortunately - in practice JS optimization is a mix of black magic and cargo cult wisdom that can become outdated as engines improve, and I can see that causing a lot of long term drag on productivity as engine authors have to keep tuning their engines for bad code.
I hope you keep getting traction on exposing developers to V8 internals; the stuff I've learned about both V8 and spidermonkey internals has been very useful so far - my complaint is largely that the learning process is difficult, not that there's anything wrong with your codebase :) I love that so many of the v8 JS builtins are self-hosted in JS instead of C++ - makes it much easier to peek under the hood and figure out what they're doing!
The problem with documenting internals is that it becomes a contract. Developers then start relying on those documented behaviors, and it later becomes much more difficult to change them.
It's bad enough as is with developers relying on undocumented behavior, see the troubles Wine (and Microsoft as well) with applications that touch Windows internals.
The problem with NOT documenting PUBLIC APIs is that all behaviour becomes, from the client perspective, undefined.
People keep going back to the point of private API docs - private details are private for a reason. Nobody but the v8 devs need private internal docs, and those MIGHT exist in encyclopedic form somewhere in Google. Those don't interest me. Public APIs are missing (or exceedingly poor, relative to v8's scope).
Isn't it the right thing to do though? Open source should not be about hiding behaviors behind undocumented code. Open source is about documenting it so that others can learn and jump in and help. It seems totally non-open if this is how V8 is developed.
There is a distinction between documenting the portions of your app you intend people use, and effectively promising to maintain side effects and accidents of your existing design. mraleph says the public API is documented, which fulfills the obligation an open source project has.
However, the discussion here is about side effects of the V8 implementation, as they relate to performance. That is to say, the V8 team is reluctant to do anything that suggests "if you write javascript using this pattern, your code will/will not run fast, but only because that's just how this week's code branch works out". If the team made those sorts of promises with a project as complex as V8, they effectively become locked in to their existing code, unable to change or improve much of anything because they'd be breaking the promises of performance patterns they previously issued.
The authors who are working with V8, on the other hand, require those promises to be made. It's not enough for the performance patterns to be documented, these authors need them to be fairly stable as well.
It's a tough situation - the V8 authors have made all the promises and documentation that's practical for them to do, but it's not enough to satisfy these other project authors' needs.
you confuse open source with extensible/flexibility/maintainability.
Its open source if you have access to the source, not because you can grok the code.
The internals of V8 ought to be undocumented, if it not intended to be an api that other systems interfaces with. Api behaviour should be documented, and i assume that's what the V8 team does - but the internal IR, for example, is private and its behaviour should not be relied up on, or do so at your own risk.
it is experimental, alpha quality, and developed only by me. It has more public API docs than v8. i cannot for the life of me comprehend how, given the vast amount of Hacker Skill in the v8 team, so little documentation (often of useless quality) comes out of it. i don't have the headers with me now but the last time i looked at the docs for Context::EnterContext(), they said, "enters the context." No joke.
I must say that public facing API is well documented right in the header files. Each class and majority of important functions have long comments[1]. So claiming that V8 has an anti-documenation culture is incorrect. Next I would like to note that V8 is surely open to patches that improve documentation of public V8 interfaces. I don't remember a lot of those patches flying in though.
Finally, documenting internals is completely different from documenting API. I don't think it is feasible to maintain such documentation. Internals exist only to rely on them in an extreme cases and in such extreme cases reaching to V8 developers directly or reading the source code is the only way to get correct and what is more important up to date information given how things are constantly in flux.
[1] https://code.google.com/p/v8/source/browse/trunk/include/v8....